Skip to main content
Version: v1

API Token Overview

All Beyond Identity API endpoints require authentication using an access token. The access token is generated through OAuth 2.0 or OIDC, using the authorization code flow or the client credentials flow. All access tokens are JWT. Two token formats are supported: self-contained tokens as JWS and referential tokens as JWE. The default token on creation is self-contained.

You can obtain an access token either through:

  1. Beyond Identity Admin Console
  2. Beyond Identity APIs

The access token should be generated with your Beyond Identity Management API application in order to access any of the Beyond Identity APIs. The "Beyond Identity Management API" application is provided by default as part of the tenant onboarding process.

The access token must be provided in the Authorization header of an API request like the following:

curl https://api-us.beyondidentity.com/v1/... \
-X $HTTP_METHOD -H "Authorization: Bearer $TOKEN"

API access tokens are valid for 3 months (TTL 7776000 seconds). You can restrict the token's access with scopes by selecting a list in the Beyond Identity Admin Console or specifying a space-separated string of scopes in your API request, in accordance with RFC6749#3.3. Token expiration can be configured from your "Beyond Identity Management API" application.

Create Token with the Beyond Identity Admin Consoleโ€‹

The simplest way to acquire an access token is through the Beyond Identity Admin Console. Under the "Apps" tab, select the "Beyond Identity Management API" application, navigate to the "API TOKENS" tab, and then click on "Create token". From there you can configure the token with a Name and specified list of Scopes.

Create Token with the Beyond Identity APIโ€‹

Alternatively, an access token may also be generated directly via API by requesting a token for the Beyond Identity Management API application. You will need the "Beyond Identity Management API" application's CLIENT_ID, CLIENT_SECRET and APPLICATION_ID. These values can be found either through the Beyond Identity Admin Console under the "Beyond Identity Admin" realm and selecting the "Beyond Identity Management API" application, or by API after retrieving the management application. In accordance with RFC6749#3.3, the scopes are expressed as a space-delimited string. If you do not specify a list of scopes, all of the available scopes will be assigned to your token on creation. For more information on available scopes, check out Scopes.

Client Credentials Flowโ€‹

/token
1
2
3
4
5
curl "https://auth-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/applications/$(MANAGEMENT_APPLICATION_ID)/token" \
-X POST \
-u "$(MANAGEMENT_API_CLIENT_ID):$(MANAGEMENT_API_CLIENT_SECRET)" --basic \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&scope=$(SCOPES)"

Authorization Code Flowโ€‹

Using the authorization code flow is a two part process. First an authorization grant code must be obtained. This code is recieved through your callback specified in the redirect_uri. When extracting the code, your state and PKCE should be validated. Second you must use the grant code to create an access token.

Use the following curl examples below to obtain an authorization code and then create a token with that code. Note the following example uses S256, but using the plain code_challenge_method might be easier to get started as using PKCE requires storing the hash of the value passed as code_challenge so it can be passed to the token endpoint later.

  1. Authenticate to obtain an authorization code:
/authorize
1
2
3
4
5
6
7
8
curl "https://auth-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/applications/$(MANAGEMENT_APPLICATION_ID)/authorize" \
-d "response_type=code" \
-d "client_id=$(MANAGEMENT_API_CLIENT_ID)" \
-d "redirect_uri=$(REDIRECT_URI)" \
-d "scope=openid" \
-d "state=$(STATE)" \
-d "code_challenge=$(OPTIONAL_CODE_CHALLENGE)" \
-d "code_challenge_method=S256"
  1. Create an access token the with authorization code:
/token
1
2
3
4
curl "https://auth-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/applications/$(MANAGEMENT_APPLICATION_ID)/token" \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=$(CODE)&scope=$(SCOPES)&client_id=$(MANAGEMENT_API_CLIENT_ID)&code_verifier=$(OPTIONAL_CODE_VERIFIER)"

Token Configurationโ€‹

Token configuration, such as expiration and default allowed scopes, can be modified either through the Beyond Identity Admin Console or through API on application update.

In the Beyond Identity Admin Console under the "Apps" tab, select the "Beyond Identity Management API" application. Then tap on "EXTERNAL PROTOCOL" and scroll down to the bottom to see "Token Configuration".

Token Configuration

Revoking Access Tokensโ€‹

In order to revoke an access token, you must be passed authentication in the form of either Bearer or Basic.

In the case of Basic authentication, the passed authentication must come from the confidential Application that the token has been minted for. The passed access token must be signed by the same client id as the application.

In the case of Bearer authentication, the passed authentication must contain the scope "tokens:delete".

Note that passing an invalid token, or a token which has already been revoked or expired, will produce a success response, pursuant to RFC7009ยง2.2.

/revoke
1
2
3
4
5
curl "https://auth-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/applications/$(MANAGEMENT_APPLICATION_ID)/revoke" \
-X POST \
-H "Authorization: Bearer $(TOKEN)" \
-H "Content-Type: application/json" \
-d "{\"token\":\"$(TOKEN_TO_REVOKE)\"}"

Validating Access Tokensโ€‹

There are two token formats that can be validated: self-contained or referential. When validating self-contained tokens, consider if you want to revoke your tokens. If revoked tokens are accepted (as in a MVP case), then the token can be validated offline by validating the signature and parsing the claims of the JWT token. In all other cases the token should be introspected.

Introspection (Online Validation)โ€‹

A successful introspect query will return information about the token. After receiving information about the token, validate that token has the expected scopes.

/introspect
1
2
3
4
5
curl "https://auth-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/introspect" \
-X POST \
-u "$(MANAGEMENT_API_CLIENT_ID):$(MANAGEMENT_API_CLIENT_SECRET)" --basic \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "{\"token\":\"$(TOKEN_TO_INTROSPECT)\"}"

Offline Validationโ€‹

In order to validate a token offline, the JWT header and claims must be decoded. Decode both and follow the steps below:

  1. Parse the host of the URI in the jku header field. If it equals auth-$REGION.beyondidentity.com, then proceed. Otherwise, reject the token.
  2. Download the public key for token validation from the jku in the JWT header. The key can be cached for the number of seconds specified by the Cache-Control max-age directive. Check the token signature against the key with matching kid downloaded from jku.
  3. Check that either the application id or resource server identifier is listed in the aud of the JWT claims. It is sufficient if at least one of the allowed audiences is in the token aud claim.
  4. Check timestamps in JWT claims where nbf <= current time as unix timestamp in seconds <= exp
  5. Check that JWT claims target tenant bi_t and target realm bi_r match the tenant and realm for the given application.
  6. Check that JWT claims has the expected scopes.