Manage users, API keys and access control

You invite users, create an API key, grant access to an account resource and inspect effective permissions. You can also manage invitations and membership at organization scope.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• Administrator access for the account or organization you manage. Set ACCOUNT_ID and ORGANIZATION_ID from your selected portal context, MEMBER_ID to an account membership identifier, and HTTP_LB_ID to the resource you will grant.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
ACCOUNT_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_ID	Returned resource identifier, or your selected scope identifier.
MEMBER_ID	Returned resource identifier, or your selected scope identifier.
ORGANIZATION_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'ACCOUNT_ID: ' ACCOUNT_ID
export ACCOUNT_ID

Steps

1. Invite an account member.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/accounts/$ACCOUNT_ID/invitations" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"invitation":{"email":"user@example.com","isAdmin":false}}'

   API reference: Create an account invitation

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

2. If you manage organization membership, invite at organization scope.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/organizations/$ORGANIZATION_ID/invitations" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"invitation":{"email":"user@example.com","isAdmin":false}}'

   API reference: Create an organization invitation

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

3. Create a key with explicit read-only access.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/user/api-keys" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"apiKey":{"name":"monitoring","accessMode":"read-only"}}'

   API reference: Create an API key for your account user

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200
   }

   Keep the returned credential private. TODO(verify): Credential return fields, display-once behavior and the key-to-account selection procedure.

4. Grant the account member read-only access to one HTTP load balancer.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/accounts/$ACCOUNT_ID/resource-permissions" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'resourcePermission': {'resource': {'resourceType': 'httpLb', 'resourceId': int(os.environ['HTTP_LB_ID'])}, 'grantee': {'granteeType': 'member', 'granteeId': int(os.environ['MEMBER_ID'])}, 'access': 'read-only'}}))
   PYBODY

   API reference: Create a resource permission grant

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

5. Inspect that member's effective access.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/accounts/$ACCOUNT_ID/members/$MEMBER_ID/effective-access" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Return effective resource access for an account member

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

6. Inspect your effective account access.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/accounts/$ACCOUNT_ID/effective-access" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Return effective resource access for the authenticated account user

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

Verify

Test the intended API operation using the member's own credential in the intended account context. A resource grant does not establish access to other accounts or resources. Review API-surface grants, teams and capability grants when effective access differs.

Troubleshooting

Symptom	Cause	Fix
API returns 401	Key mode, membership or resource permission denies the operation	Check active membership, selected account, expiry, revocation and effective grants.
Grant targets the wrong user	Identity identifier was used instead of membership identifier	Use the account membership identifier.
Organization access differs from account access	Organization and account memberships are separate	Inspect membership and grants at the intended scope.

Limits and defaults

Setting	Limit or default
API key name	1 to 64 characters
API key access mode	Default admin; read-only, write or admin
Invitation expiry	Default 7 days
Invitation administrator flag	Default false
Resource access	read-only, write or admin

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
409	Resource state conflicts with the operation.
500	The request encounters a server error.

Related API operations

• DELETE /accounts/{accountId}/api-surface-fallbacks/{apiSurfaceFallbackId}
• DELETE /accounts/{accountId}/api-surface-grants/{apiSurfaceGrantId}
• DELETE /accounts/{accountId}/capability-grants/{capabilityGrantId}
• DELETE /accounts/{accountId}/invitations/{invitationId}
• DELETE /accounts/{accountId}/members/{accountUserId}
• DELETE /accounts/{accountId}/resource-permissions/{resourcePermissionId}
• DELETE /accounts/{accountId}/sso-providers/{ssoProviderId}
• DELETE /accounts/{accountId}/teams/{teamId}
• DELETE /accounts/{accountId}/teams/{teamId}/members/{accountUserId}
• DELETE /organizations/{organizationId}
• DELETE /organizations/{organizationId}/accounts/{accountId}
• DELETE /organizations/{organizationId}/capability-grants/{capabilityGrantId}
• DELETE /organizations/{organizationId}/invitations/{invitationId}
• DELETE /organizations/{organizationId}/sso-providers/{ssoProviderId}
• DELETE /organizations/{organizationId}/teams/{teamId}
• DELETE /user/api-keys/{apiKeyId}
• DELETE /user/mfa-factors/{mfaFactorId}
• GET /accounts/{accountId}
• GET /accounts/{accountId}/api-surface-fallbacks
• GET /accounts/{accountId}/api-surface-grants
• GET /accounts/{accountId}/audit-logs
• GET /accounts/{accountId}/auth-logs
• GET /accounts/{accountId}/capability-grants
• GET /accounts/{accountId}/effective-access
• GET /accounts/{accountId}/invitations
• GET /accounts/{accountId}/members
• GET /accounts/{accountId}/members/{accountUserId}
• GET /accounts/{accountId}/members/{accountUserId}/effective-access
• GET /accounts/{accountId}/resource-permissions
• GET /accounts/{accountId}/sso-providers
• GET /accounts/{accountId}/sso-providers/{ssoProviderId}
• GET /accounts/{accountId}/teams
• GET /accounts/{accountId}/teams/{teamId}
• GET /accounts/{accountId}/teams/{teamId}/members
• GET /auth/contexts
• GET /organizations
• GET /organizations/{organizationId}
• GET /organizations/{organizationId}/accounts
• GET /organizations/{organizationId}/audit-logs
• GET /organizations/{organizationId}/auth-logs
• GET /organizations/{organizationId}/capability-grants
• GET /organizations/{organizationId}/invitations
• GET /organizations/{organizationId}/members
• GET /organizations/{organizationId}/sso-providers
• GET /organizations/{organizationId}/sso-providers/{ssoProviderId}
• GET /organizations/{organizationId}/teams
• GET /organizations/{organizationId}/teams/{teamId}
• GET /user
• GET /user/account-invitations
• GET /user/api-keys
• GET /user/mfa-factors
• GET /user/organization-invitations
• PATCH /accounts/{accountId}
• PATCH /accounts/{accountId}/invitations/{invitationId}
• PATCH /accounts/{accountId}/members/{accountUserId}
• PATCH /accounts/{accountId}/resource-permissions/{resourcePermissionId}
• PATCH /accounts/{accountId}/sso-providers/{ssoProviderId}
• PATCH /accounts/{accountId}/teams/{teamId}
• PATCH /organizations/{organizationId}
• PATCH /organizations/{organizationId}/invitations/{invitationId}
• PATCH /organizations/{organizationId}/sso-providers/{ssoProviderId}
• PATCH /organizations/{organizationId}/teams/{teamId}
• PATCH /user
• PATCH /user/api-keys/{apiKeyId}
• PATCH /user/mfa-factors/{mfaFactorId}
• POST /accounts/{accountId}/api-surface-fallbacks
• POST /accounts/{accountId}/api-surface-grants
• POST /accounts/{accountId}/capability-grants
• POST /accounts/{accountId}/invitations
• POST /accounts/{accountId}/invitations/{invitationId}/resend
• POST /accounts/{accountId}/members/{accountUserId}/api-keys/revoke
• POST /accounts/{accountId}/members/{accountUserId}/sessions/revoke
• POST /accounts/{accountId}/members/{accountUserId}/transfer-master
• POST /accounts/{accountId}/resource-permissions
• POST /accounts/{accountId}/sso-providers
• POST /accounts/{accountId}/sso-providers/{ssoProviderId}/verify
• POST /accounts/{accountId}/teams
• POST /accounts/{accountId}/teams/{teamId}/members
• POST /auth/context
• POST /auth/email-verifications/{token}/confirm
• POST /auth/invitations/{invitationToken}/accept
• POST /auth/login
• POST /auth/login/mfa
• POST /auth/onboarding
• POST /auth/organization-invitations/{invitationToken}/accept
• POST /auth/password-resets
• POST /auth/password-resets/{token}/confirm
• POST /auth/phone-verifications/{token}/confirm
• POST /organizations
• POST /organizations/{organizationId}/accounts
• POST /organizations/{organizationId}/accounts/{accountId}/members/{accountUserId}/api-keys/revoke
• POST /organizations/{organizationId}/accounts/{accountId}/members/{accountUserId}/sessions/revoke
• POST /organizations/{organizationId}/capability-grants
• POST /organizations/{organizationId}/invitations
• POST /organizations/{organizationId}/invitations/{invitationId}/resend
• POST /organizations/{organizationId}/members/{organizationUserId}/transfer-master
• POST /organizations/{organizationId}/sso-providers
• POST /organizations/{organizationId}/sso-providers/{ssoProviderId}/verify
• POST /organizations/{organizationId}/teams
• POST /user/account-invitations/{invitationId}/accept
• POST /user/api-keys
• POST /user/email-verifications
• POST /user/mfa-factors
• POST /user/mfa-factors/{mfaFactorId}/verify
• POST /user/organization-invitations/{invitationId}/accept
• POST /user/phone-verifications
• POST /user/phone-verifications/{challengeId}/confirm
• POST /user/recovery-codes/rotate
• POST /user/sessions/revoke

API reference

• Delete an account API surface fallback

• Delete an account API surface grant

• Delete an account capability grant

• Delete an account invitation

• Remove an account member

• Delete a resource permission grant

• Delete an account SSO provider

• Delete an account team

• Remove an account user from a team

• Delete an empty organization container

• Detach an account from an organization

• Delete an organization capability grant

• Delete an organization invitation

• Delete an organization SSO provider

• Delete an organization team

• Delete an API key for your account user

• Delete an MFA factor

• Return one account

• List account API surface fallbacks

• List account API surface grants

• List account audit logs

• List account authentication logs

• List account capability grants

• Return effective resource access for the authenticated account user

• List account invitations

• List members in an account

• Return one account member

• Return effective resource access for an account member

• List account resource permission grants

• List account SSO providers

• Return one account SSO provider

• List account teams

• Return one account team

• List account users assigned to a team

• List available account and organization contexts

• List organizations available to the authenticated user

• Return one organization

• List accounts attached to an organization

• List organization audit logs

• List organization authentication logs

• List organization capability grants

• List organization invitations

• List organization members

• List organization SSO providers

• Return one organization SSO provider

• List organization teams

• Return one organization team

• Get your profile and preferences

• List pending account invitations for the authenticated user

• Returns your account user's API keys

• Returns the current user's MFA factors

• List pending organization invitations for the authenticated user

• Update account profile and security defaults

• Update an account invitation

• Update account member admin and account-scoped security settings

• Update a resource permission grant

• Update an account SSO provider

• Update an account team

• Update an organization container

• Update an organization invitation

• Update an organization SSO provider

• Update an organization team

• Update the current Balancer user's profile and UI preferences

• Update an API key for your account user

• Update an MFA factor

• Create or update an account API surface fallback

• Create or update an account API surface grant

• Create an account capability grant

• Create an account invitation

• Resend a pending account invitation

• Revoke all active API keys for an account member

• Revoke an account member's account-scoped Balancer sessions

• Transfer account master ownership to another active account member

• Create a resource permission grant

• Create an account SSO provider

• Verify an account SSO provider email-domain configuration

• Create an account team

• Add an account user to a team

• Create an account or organization context JWT

• Confirm an email verification token

• Accept an account invitation and create or attach the invited user

• Authenticate with a Balancer user password and issue an identity JWT

• Complete a Balancer login that requires MFA

• Create a new Balancer account identity through self-serve onboarding

• Accept an organization invitation

• Request a password reset email for a Balancer user

• Confirm a Balancer password reset token and set a new password

• Confirm a phone verification token

• Create an organization container

• Attach an existing account to the organization

• Revoke all active API keys for an account member

• Revoke account-scoped sessions for an account member

• Create an organization capability grant

• Create an organization invitation

• Resend a pending organization invitation

• Transfer organization master ownership

• Create an organization SSO provider

• Verify an organization SSO provider email-domain configuration

• Create an organization team

• Accept a pending account invitation for the authenticated user

• Create an API key for your account user

• Create an email verification challenge for the current user

• Create an MFA factor for the current user

• Verify an MFA factor with a current authenticator code

• Accept a pending organization invitation for the authenticated user

• Create a phone verification challenge for the current user

• Confirm a phone verification challenge for the current user

• Rotate the current user's recovery codes

• Revoke your account-scoped Balancer session

• Authentication

• User

• Accounts

• Access Control

• Organizations

Need Help?

Contact your account manager or use the Balancer portal.