Skip to main content
Version: v2

Create a Beyond Identity Management API token

Last updated on

You can automate administrative tasks for your Beyond Identity tenant using the Beyond Identity Management API.
All of the functionality available in the Beyond Identity Admin Console is also available through the API.
In order to call the API, you must create access tokens for the Beyond Identity Management API resource server that include the scopes your app or script will need, and then configure your app or script to use the the tokens in API calls.

Prerequisites​

In order to request an access token, you need to have an app configured in your Beyond Identity tenant.

For Beyond Identity Management API access tokens, this can be the built in Beyond Identity Management API app or another app you create that points to the 'Beyond Identity Management API' Resource Server.

Select your scopes​

Before creating or requesting any tokens for the Beyond Identity Management API (or for any resource), determine the list of scopes the tokens must have, which will determine what access your app or script will have to which resources.
The Beyond Identity Management API documentation provides the required scopes for each supported API action within the "Authorizations" section.
For example, when creating a Realm, the access token must contain the realms:create scope as shown below:
API Create Realm Required Scopes

Admin Console​

The simplest way to acquire an access token for the Beyond Identity Management API is interactively through the Beyond Identity Admin Console.

You can also request the token programmatically using OAuth or OIDC flows.

Create access token in the console​

  1. Under Apps, select the app for which you want a token, such as the Beyond Identity Management API application.

    Beyond Identity Management API

  2. Select the API Tokens tab, and then click on Create token. (Note that the API Tokens tab only exists for apps that use the client credentials grant type. For apps that use the authorization code grant type, you'll need to request the token programmatically. )

    Beyond Identity Management API > Create token

  3. Configure the token with a Name, modify the list of Scopes based on your use case, and click Create token.

note

Note that the list of Scopes available to request comes from the Resource Server associated with the app.

Create access token via API​

To request tokens for the Beyond Identity Management API programmatically, we recommend that you create an app that references the 'Beyond Identity Management API' Resource Server, then send a request to the app's /authorize and/or /token API endpoints following the OAuth and OIDC protocols.

Follow the steps below based on the flow you wish to use, either client credentials or authorization code:

  1. Create an app with the following properties:

    PropertyValue
    ProtocolOAuth2
    Client TypeConfidential
    PKCEDisabled
    Token Endpoint Auth MethodClient Secret Basic
    Grant TypeClient Credentials
    Resource ServerBeyond Identity Management API
    Allowed Scopesadd the scopes required for the API call based on the Beyond Identity Management API documentation

  2. Fill in a Display Name, then click Submit to save the app.

  3. Next, create the /token request as shown below:

    /token
    1
2
3
4
5
curl "https://auth-$(us|eu).beyondidentity.com/v1/tenants/$(tenant_id)/realms/$(realm_id)/applications/$(application_id)/token" \
-X POST \
-u "$(client_id):$(client_secret)" --basic \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&scope=$(scope)"

    where:

    • application_id is the Application ID of the app you created

    • client_id and client_secret are the Client ID and Client Secret, respectively, of the app you created

    • scopes is one or more of the app's Allowed Scopes, space delimited, and includes the required scopes for the API call(s) your app will make