Authentication

Choose credentials for the context you need. A sign-in token identifies you; an account token or account API key authorizes account operations.

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.

Credential contexts

Credential	Accepted operations and scope
Email and password	POST /auth/login, returns an identity token or an MFA challenge.
MFA challenge plus factor	POST /auth/login/mfa, completes sign-in.
Identity bearer token	GET /auth/contexts lists available accounts and organizations. POST /auth/context enters one of those contexts. It also supports organization listing and creation and identity invitation operations. It does not authorize account resource operations.
Account bearer token	Account resources, account membership and user operations, subject to permissions.
Organization bearer token	Operations within a selected organization, subject to organization membership and permissions. Organization listing and creation require an identity token. It does not replace an account token for account resources.
Account API key	Account operations that accept API keys, subject to key access mode and membership permissions. Identity-context endpoints and session revocation reject it.

Send bearer tokens with Authorization: Bearer $BALANCER_TOKEN. Send an API key with x-api-key: $BALANCER_API_KEY or the key query parameter. Credential precedence is key, then x-api-key, then bearer. If you send both key forms, the query parameter wins. Use one credential per request.

Operations that require a human token

API keys do not replace a human account bearer token for the following operations:

Operation family	Required credential
Read or update your user profile	Human account bearer token.
Email and phone verification requests, phone challenge confirmation	Human account bearer token.
MFA factor management and recovery-code rotation	Human account bearer token.
Revoke your account sessions	Human account bearer token.
Update account settings	Human account bearer token with the required account permissions.
Resend account invitations	Human account bearer token with the required account permissions.
Revoke a member's API keys or sessions	Human account bearer token with the required account permissions.
Transfer account ownership	Human account bearer token belonging to the current account master.
List or create organizations	Identity bearer token.
List or accept your account and organization invitations	Identity bearer token.
Manage a selected organization's settings, accounts, teams, invitations, grants or sign-in providers	Organization bearer token with the required permissions.

Key scopes and defaults

API keys belong to the current account membership. A key does not bypass account ownership, resource grants or capability checks. Account and organization administrators are customer roles.

Access mode	Allowed request rank
read-only	GET, HEAD, OPTIONS and designated POST analytics queries.
write	Read access and other write requests, including POST and PATCH.
admin	Read, write and DELETE. This is the default when creating a key.

An API-key caller cannot create or update a key with greater access than its own. Expiration is capped by the effective membership, account and team lifetime. Expired and deleted keys cannot authenticate. Key creation returns the generated key; listing and updating return metadata without key material.

Sign in

Set BALANCER_API_BASE to https://<your-api-host>, using the host shown in the Balancer portal. The following commands use jq to construct JSON and read responses.

1. Read your credentials and sign in.

   read -r -p 'Email: ' BALANCER_EMAIL
   read -r -s -p 'Password: ' BALANCER_PASSWORD
   printf '\n'
   jq -n --arg email "$BALANCER_EMAIL" --arg password "$BALANCER_PASSWORD" \
     '{email:$email,password:$password}' |
     curl --silent --show-error "$BALANCER_API_BASE/auth/login" \
       -H 'Content-Type: application/json' --data-binary @- > login.json
   unset BALANCER_PASSWORD
   cat login.json

   Expect HTTP 200. Without MFA, data.token is an identity bearer token, data.session.type is identity and data.expiresIn is 3600 seconds. Verify those fields before continuing.

2. If data.mfaRequired is true, complete MFA within the 300-second challenge lifetime.

   read -r -p 'Authenticator code: ' BALANCER_MFA_CODE
   jq --arg code "$BALANCER_MFA_CODE" \
     '{mfaChallengeToken:.data.mfaChallengeToken,code:$code}' login.json |
     curl --silent --show-error "$BALANCER_API_BASE/auth/login/mfa" \
       -H 'Content-Type: application/json' --data-binary @- > identity.json
   cat identity.json

   Expect HTTP 200 with data.token, data.session.type equal to identity and data.expiresIn equal to 3600. Supply exactly one of code or recoveryCode. A recovery code is consumed on use. If MFA is not required, copy the response before step 3:

   cp login.json identity.json

3. List contexts to verify the identity token.

   BALANCER_IDENTITY_TOKEN=$(jq -r '.data.token' identity.json)
   curl --silent --show-error "$BALANCER_API_BASE/auth/contexts" \
     -H "Authorization: Bearer $BALANCER_IDENTITY_TOKEN" > contexts.json
   cat contexts.json

   Expect HTTP 200 with data.accounts and data.organizations. Verify that the desired context appears.

4. Enter an account context. Set BALANCER_ACCOUNT_ID from the selected entry in contexts.json.

   read -r -p 'Account identifier from contexts: ' BALANCER_ACCOUNT_ID
   jq -n --argjson id "$BALANCER_ACCOUNT_ID" \
     '{context:{type:"account",accountId:$id}}' |
     curl --silent --show-error "$BALANCER_API_BASE/auth/context" \
       -H "Authorization: Bearer $BALANCER_IDENTITY_TOKEN" \
       -H 'Content-Type: application/json' --data-binary @- > account-context.json
   cat account-context.json

   Expect HTTP 200 with data.token and data.session.type equal to account. Verify the returned account matches your selection. For an organization, use context type organization and field organizationId instead.

Revoke credentials

Deleting a key through DELETE /user/api-keys/{apiKeyId} removes it from subsequent authentication. The key must belong to your current account membership. DELETE requires admin access.

POST /user/sessions/revoke requires a human account bearer token. It rejects API keys and identity tokens. It invalidates all account tokens tied to your current membership, including the calling token. Other account memberships and your identity context remain valid.

1. Send the account session revocation request.

   BALANCER_TOKEN=$(jq -r '.data.token' account-context.json)
   curl --silent --show-error -X POST "$BALANCER_API_BASE/user/sessions/revoke" \
     -H "Authorization: Bearer $BALANCER_TOKEN"

   Expect HTTP 200 with data.revoked and data.scope.

2. Verify that the old token fails an account request.

   curl --silent --show-error -i "$BALANCER_API_BASE/http-loadbalancers" \
     -H "Authorization: Bearer $BALANCER_TOKEN"

   Expect HTTP 401. Enter the account context again with a valid identity token to obtain a new account token.

TODO(verify): Confirm identity and organization session revocation and refresh behavior beyond account session revocation.