PingOne Advanced Identity Cloud

Authenticate to Advanced Identity Cloud REST API with access token

You need an access token to authenticate to the following Identity Cloud REST API endpoints:

Summary of use:

  1. Create a service account in the Advanced Identity Cloud admin UI and download a private key.

  2. Create a JWT and sign it using the private key.

  3. Create an access token using the JWT profile for OAuth 2.0 authorization grant flow.

  4. Set the access token as a bearer token in the Authorization HTTP header for each API request:

    Authorization: Bearer <access-token>

Get an access token


You need the jose command-line tool to run some of the commands below. To find installation instructions for your particular package manager, refer to

Step 1: Create a service account and download its private key

  1. Follow the steps in Create a new service account.

    1. In step 9, save the private key as a local file called key.jwk.

    2. Make a note of the ID for the service account you created. An example of an ID is 449d7e27-7889-47af-a736-83b6bbf97ec5.

Step 2: Create and sign a JWT

  1. Set the following variables in your terminal, to be used as claims in a JWT payload:

    1. Set SERVICE_ACCOUNT_ID to hold the ID of the service account. For use in the iss (issuer) and sub (subject) claims.

      $ SERVICE_ACCOUNT_ID="<service-account-id>"(1)
      1 Replace <service-account-id> with the service account ID; for example, 449d7e27-7889-47af-a736-83b6bbf97ec5.
    2. Set AUD to hold the URL (including port number) where the JWT will be used to request the access token. For use in the aud (audience) claim.

      $ AUD='https://<tenant-env-fqdn>:443/am/oauth2/access_token'
    3. Set EXP to hold a 3-minute expiration time for the JWT, expressed as number of seconds since the Unix epoch. For use in the exp (expiration time) claim.

      $ EXP=$(($(date -u +%s) + 180))
    4. Set JTI to hold a unique ID for the JWT. For use in the jti (JWT ID) claim.

      $ JTI=$(openssl rand -base64 16)
  2. Combine the claims to create a payload for the JWT:

    $ echo -n "{
    }" > payload.json
  3. Sign the JWT using the private key you downloaded and saved as key.jwk in step 1a:

    $ jose jws sig -I payload.json -k key.jwk -s '{"alg":"RS256"}' -c -o jwt.txt

Step 3: Get an access token using the JWT profile authorization grant

  1. Request an access token from the /oauth2/access_token endpoint using the JWT:

    $ curl \
    --request POST ${AUD} \
    --data "client_id=service-account" \(1)
    --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \(2)
    --data "assertion=$(< jwt.txt)" \(3)
    --data "scope=<scope>"(4)
    1 The client ID service-account targets the built-in OAuth 2.0 public client for service accounts. The client only allows the JWT profile for OAuth 2.0 authorization grant flow.

    + NOTE: Access the built-in OAuth 2.0 public client using the tenant FQDN. You cannot access it using an Alpha or Bravo realm alias URL or a custom domain URL.

    2 The grant type urn:ietf:params:oauth:grant-type:jwt-bearer represents the JWT profile for OAuth 2.0 authorization grant flow.
    3 The assertion parameter is populated with the output of the signed JWT from step 2c.
    4 Replace <scope> with a scope or a space delimited set of scopes; for example, fr:idc:esv:* or fr:am:* fr:idm:*. Refer to Service account scopes. The specified scopes must be the same as (or a subset of) the scopes that you assigned to the service account.
  2. Examine the response to find the access token, represented as access_token:

        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...8ECmkyDJKow8Qp_Tnp_lGNRJzLWi18iUGQrCTtxyTXw",
        "scope": "fr:am:* fr:idm:*",
        "token_type": "Bearer",
        "expires_in": 899

Use an access token

To use the access token with the REST API, set it as a bearer token in the Authorization HTTP header for each API request.

The following example uses the access token to get a list of identities:

Show request
$ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/managed/<realm>_user?_fields=userName,givenName,sn,mail,accountStatus&_prettyPrint=true&_queryFilter=true' \(1)
--header 'Authorization: Bearer <access-token>'(2)
1 Replace <realm> with the realm where you created the access token.
2 Replace <access-token> with the access_token in the authentication response (refer to Get an access token).
Show response
    "result": [
            "_id": "f413db4c-cebd-4950-81e6-57bdb47921a4",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": ""
            "_id": "15249a65-8f9a-4063-9586-a2465963cee4",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser2",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": ""
            "_id": "30485bc4-fdbb-4946-8ce4-1a53c6824d92",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser3",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": ""
    "resultCount": 3,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
Copyright © 2010-2024 ForgeRock, all rights reserved.