Authenticate to Identity Cloud REST API with Session Token

Overview

You will need a session token to authenticate to the following Identity Cloud REST API endpoint:

  • /am/*

The /am/* endpoint exposes many, but not all, of the AM APIs to Identity Cloud. For an expanded list of endpoints, see AM REST API Endpoints.

Get an administrator session token

For background information on sessions and session tokens, see Introducing Sessions.

  1. Start an authentication journey:

    Show request
    $ curl \
      --request POST 'https://<tenant-name>.forgeblocks.com/am/json/authenticate' \
      --header 'Content-Type: application/json' \
      --header 'Accept-API-Version: resource=2.1'
  2. View the response to see the authId and callbacks:

    Show response
    {
        "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...JgXXlA1ke3zcOuiA0CbC8EnhLX1MzIIU6VNgw4uq_Js",
        "callbacks": [
            {
                "type": "NameCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "User Name"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken1",
                        "value": ""
                    }
                ],
                "_id": 0
            },
            {
                "type": "PasswordCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "Password"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken2",
                        "value": ""
                    }
                ],
                "_id": 1
            }
        ]
    }
  3. Submit the authId and callbacks received in the previous response, specifying the username and password of an Identity Cloud administrator in the callbacks:

    Show request
    $ curl \
    --request POST 'https://<tenant-name>.forgeblocks.com/am/json/authenticate' \
    --header 'Content-Type: application/json' \
    --header 'Accept-API-Version: resource=2.1, protocol=1.0' \
    --data-raw '{
        "authId": "<auth-id>", (1)
        "callbacks": [
            {
                "type": "NameCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "User Name"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken1",
                        "value": "<idcloud-administrator-user-name>"  (2)
                    }
                ],
                "_id": 0
            },
            {
                "type": "PasswordCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "Password"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken2",
                        "value": "<idcloud-administrator-password>"  (3)
                    }
                ],
                "_id": 1
            }
        ]
    }'
    1 Replace <auth-id> with authID from the response in the previous step
    2 Replace <idcloud-administrator-username> with an Identity Cloud administrator username
    3 Replace <idcloud-administrator-password> with an Identity Cloud administrator password
  4. View the response to see the new authId and MFA-skip callbacks:

    Show response
    {
        "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...AzkH7fJGh9AzcDzsqxMaJsSNgjfQ-G5vGddOScVdDVQ",
        "callbacks": [
            {
                "type": "TextOutputCallback",
                "output": [
                    {
                        "name": "message",
                        "value": "message-952"
                    },
                    {
                        "name": "messageType",
                        "value": "0"
                    }
                ]
            },
            {
                "type": "ConfirmationCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": ""
                    },
                    {
                        "name": "messageType",
                        "value": 0
                    },
                    {
                        "name": "options",
                        "value": [
                            "Set up"
                        ]
                    },
                    {
                        "name": "optionType",
                        "value": -1
                    },
                    {
                        "name": "defaultOption",
                        "value": 0
                    }
                ],
                "input": [
                    {
                        "name": "IDToken2",
                        "value": 0
                    }
                ]
            },
            {
                "type": "HiddenValueCallback",
                "output": [
                    {
                        "name": "value",
                        "value": "false"
                    },
                    {
                        "name": "id",
                        "value": "skip-input-952"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken3",
                        "value": "skip-input-952"
                    }
                ]
            },
            {
                "type": "TextOutputCallback",
                "output": [
                    {
                        "name": "message",
                        "value": "var skipContainer = document.createElement(\"div\");skipContainer.style = \"width:100%\";skipContainer.innerHTML = \"<button id='skip-link-952' class='btn btn-block btn-link' type='submit'>Skip for now</button>\";document.getElementById(\"skip-input-952\").parentNode.append(skipContainer);document.getElementsByClassName(\"callback-component\").forEach(  function (e) {    var message = e.firstElementChild;    if (message.firstChild && message.firstChild.nodeName == \"#text\" && message.firstChild.nodeValue.trim() == \"message-952\") {      message.align = \"center\";      message.innerHTML = \"<h2 class='h2'>Set up 2-step verification</h2><div style='margin-bottom:1em'>Protect your account by adding a second step after entering your password to verify it's you signing in.</div>\";    }  })"
                    },
                    {
                        "name": "messageType",
                        "value": "4"
                    }
                ]
            },
            {
                "type": "TextOutputCallback",
                "output": [
                    {
                        "name": "message",
                        "value": "document.getElementById(\"skip-link-952\").onclick = function() {  document.getElementById(\"skip-input-952\").value = \"Skip\";  document.getElementById(\"loginButton_0\").click();  return false;}"
                    },
                    {
                        "name": "messageType",
                        "value": "4"
                    }
                ]
            }
        ]
    }
  5. Submit the new authId and MFA-skip callbacks received in the previous response:

    Show request
    $ curl \
    --request POST 'https://<tenant-name>.forgeblocks.com/am/json/authenticate' \
    --header 'Content-Type: application/json' \
    --header 'Accept-API-Version: resource=2.1, protocol=1.0' \
    --data-raw '{
        "authId": "<auth-id>", (1)
        "callbacks": [
            {
                "type": "TextOutputCallback", (2)
                "output": [
                    {
                        "name": "message",
                        "value": "Skip"
                    },
                    {
                        "name": "messageType",
                        "value": "0"
                    }
                ]
            },
            {
                "type": "ConfirmationCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": ""
                    },
                    {
                        "name": "messageType",
                        "value": 0
                    },
                    {
                        "name": "options",
                        "value": [
                            "Set up"
                        ]
                    },
                    {
                        "name": "optionType",
                        "value": -1
                    },
                    {
                        "name": "defaultOption",
                        "value": 0
                    }
                ],
                "input": [
                    {
                        "name": "IDToken2",
                        "value": 0
                    }
                ]
            },
            {
                "type": "HiddenValueCallback", (2)
                "output": [
                    {
                        "name": "value",
                        "value": "false"
                    },
                    {
                        "name": "id",
                        "value": "Skip"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken3",
                        "value": "Skip"
                    }
                ]
            }
        ]
    }'
    1 Replace <auth-id> with authID from the response in the previous step
    2 Skip MFA callbacks
  6. View the response to see the session token, represented as tokenID:

    Show response
    {
        "tokenId": "uVB-DjIYHJb99PVeIc1Y9bcD974.*AAJTSQACMDIAAlNLABxwSExZMkZLTkwvMzFjVHIwNzIyMW5UeFJCRkk9AAR0eXBlAANDVFMAAlMxAAIwMQ..*",
        "successUrl": "/platform",
        "realm": "/"
    }

Use an administrator session token

To use the session token with the REST API, set it as an HTTP header value. For the HTTP header field name, use the tenant session cookie name (found in Tenant Settings > Global Settings > Cookie).

The following example uses the session token to create a public OAuth 2.0 client:

Show request with abridged body
$ curl \
--request PUT 'https://<tenant-name>.forgeblocks.com/am/
json/realms/root/realms/<realm>/realm-config/agents/OAuth2Client/<oauth2-client-name>' \ (1) (2)
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header '<session-cookie-name>: <session-token>' \ (3) (4)
--data-raw '{
  "coreOAuth2ClientConfig": {
    ...
    "userpassword": "<oauth2-client-password>", (5)
    "clientType": {
      "inherited": false,
      "value": "Public"
    },
    "scopes": {
      "inherited": false,
      "value": [
        "write",
        "read",
        "share",
        "print",
        "copy",
        "delete",
        "manage",
        "edit"
      ]
    },
    ...
  },
  "advancedOAuth2ClientConfig": {
    ...
    "grantTypes": {
      "inherited": false,
      "value": [
        "authorization_code",
        "implicit",
        "password",
        "client_credentials",
        "refresh_token",
        "urn:ietf:params:oauth:grant-type:uma-ticket",
        "urn:ietf:params:oauth:grant-type:device_code",
        "urn:ietf:params:oauth:grant-type:saml2-bearer",
        "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "urn:openid:params:grant-type:ciba"
      ]
    },
    ...
  },
  ...
}'
1 Replace <realm> with the realm where you want to create the OAuth 2.0 client.
2 Replace <oauth2-client-name> with the name that you have chosen for the OAuth 2.0 client.
3 Replace <session-cookie-name> with the session cookie name configured for the tenant.
4 Replace <session-token> with the tokenId in the authentication response (see Get an administrator session token).
5 Replace <oauth2-client-password> with the password that you have chosen for the OAuth 2.0 client.
Show request with full body
$ curl \
--request PUT 'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/<realm>/realm-config/agents/OAuth2Client/<oauth2-client-name>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header '<session-cookie-name>: <session-token>' \
--data-raw '{
  "coreOAuth2ClientConfig": {
    "agentgroup": "",
    "status": {
      "inherited": false,
      "value": "Active"
    },

    "userpassword": "<oauth2-client-password>",
    "clientType": {
      "inherited": false,
      "value": "Public"
    },
    "loopbackInterfaceRedirection": {
      "inherited": true,
      "value": true
    },
    "redirectionUris": {
      "inherited": false,
      "value": [
        "https://httpbin.org/anything"
      ]
    },
    "scopes": {
      "inherited": false,
      "value": [
        "write",
        "read",
        "share",
        "print",
        "copy",
        "delete",
        "manage",
        "edit"
      ]
    },
    "defaultScopes": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "clientName": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "authorizationCodeLifetime": {
      "inherited": true,
      "value": 0
    },
    "refreshTokenLifetime": {
      "inherited": true,
      "value": 0
    },
    "accessTokenLifetime": {
      "inherited": true,
      "value": 0
    }
  },
  "advancedOAuth2ClientConfig": {
    "name": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "descriptions": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "requestUris": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "responseTypes": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "grantTypes": {
      "inherited": false,
      "value": [
        "authorization_code",
        "implicit",
        "password",
        "client_credentials",
        "refresh_token",
        "urn:ietf:params:oauth:grant-type:uma-ticket",
        "urn:ietf:params:oauth:grant-type:device_code",
        "urn:ietf:params:oauth:grant-type:saml2-bearer",
        "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "urn:openid:params:grant-type:ciba"
      ]
    },
    "contacts": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "tokenEndpointAuthMethod": {
      "inherited": true,
      "value": "string"
    },
    "sectorIdentifierUri": {
      "inherited": true,
      "value": "string"
    },
    "subjectType": {
      "inherited": true,
      "value": "string"
    },
    "updateAccessToken": {
      "inherited": true,
      "value": "string"
    },
    "clientUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "logoUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "policyUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "isConsentImplied": {
      "inherited": true,
      "value": true
    },
    "mixUpMitigation": {
      "inherited": true,
      "value": true
    }
  },
  "coreOpenIDClientConfig": {
    "claims": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "postLogoutRedirectUri": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "clientSessionUri": {
      "inherited": true,
      "value": "string"
    },
    "defaultMaxAge": {
      "inherited": true,
      "value": 0
    },
    "defaultMaxAgeEnabled": {
      "inherited": true,
      "value": true
    },
    "defaultAcrValues": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    },
    "jwtTokenLifetime": {
      "inherited": true,
      "value": 0
    }
  },
  "signEncOAuth2ClientConfig": {
    "jwksUri": {
      "inherited": true,
      "value": "string"
    },
    "jwksCacheTimeout": {
      "inherited": true,
      "value": 0
    },
    "jwkStoreCacheMissCacheTime": {
      "inherited": true,
      "value": 0
    },
    "tokenEndpointAuthSigningAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "jwkSet": {
      "inherited": true,
      "value": "string"
    },
    "idTokenSignedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "idTokenEncryptionEnabled": {
      "inherited": true,
      "value": true
    },
    "idTokenEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "idTokenEncryptionMethod": {
      "inherited": true,
      "value": "string"
    },
    "idTokenPublicEncryptionKey": {
      "inherited": true,
      "value": "string"
    },
    "clientJwtPublicKey": {
      "inherited": true,
      "value": "string"
    },
    "mTLSTrustedCert": {
      "inherited": true,
      "value": "string"
    },
    "mTLSSubjectDN": {
      "inherited": true,
      "value": "string"
    },
    "mTLSCertificateBoundAccessTokens": {
      "inherited": true,
      "value": true
    },
    "publicKeyLocation": {
      "inherited": true,
      "value": "string"
    },
    "userinfoResponseFormat": {
      "inherited": true,
      "value": "string"
    },
    "userinfoSignedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "userinfoEncryptedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "userinfoEncryptedResponseEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "requestParameterSignedAlg": {
      "inherited": true,
      "value": "string"
    },
    "requestParameterEncryptedAlg": {
      "inherited": true,
      "value": "string"
    },
    "requestParameterEncryptedEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionResponseFormat": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionSignedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionEncryptedResponseAlg": {
      "inherited": true,
      "value": "string"
    },
    "tokenIntrospectionEncryptedResponseEncryptionAlgorithm": {
      "inherited": true,
      "value": "string"
    }
  },
  "coreUmaClientConfig": {
    "claimsRedirectionUris": {
      "inherited": true,
      "value": [
        "Unknown Type: any"
      ]
    }
  }
}'
Show response
{
    "_id": "<oauth2-client-name>",
    "_rev": "1969048932",
    "coreOAuth2ClientConfig": {
        "agentgroup": null,
        "userpassword": null,
        "userpassword-encrypted": "AAAAA0FFUwIQov3z9VqIAZNjEIdr9/kly8jg8irlj6shFnjsLQdtFfrTROJsaLUC0w==",
        "scopes": {
            "inherited": false,
            "value": [
                "write",
                "read",
                "share",
                "print",
                "copy",
                "delete",
                "manage",
                "edit"
            ]
        },
        "clientType": {
            "inherited": false,
            "value": "Public"
        },
        "redirectionUris": {
            "inherited": false,
            "value": [
                "https://httpbin.org/anything"
            ]
        },
        "status": {
            "inherited": false,
            "value": "Active"
        }
    },
    "advancedOAuth2ClientConfig": {
        "grantTypes": {
            "inherited": false,
            "value": [
                "authorization_code",
                "implicit",
                "password",
                "client_credentials",
                "refresh_token",
                "urn:ietf:params:oauth:grant-type:uma-ticket",
                "urn:ietf:params:oauth:grant-type:device_code",
                "urn:ietf:params:oauth:grant-type:saml2-bearer",
                "urn:ietf:params:oauth:grant-type:jwt-bearer",
                "urn:openid:params:grant-type:ciba"
            ]
        }
    },
    "_type": {
        "_id": "OAuth2Client",
        "name": "OAuth2 Clients",
        "collection": true
    }
}

Get an end-user session token

  1. Start an end-user authentication journey:

    Show request
    $ curl \
      --request POST 'https://<tenant-name>.forgeblocks.com/am/
    json/realms/root/realms/<realm>/authenticate?authIndexType=service&authIndexValue=PasswordGrant' \ (1)
      --header 'Content-Type: application/json' \
      --header 'Accept-API-Version: resource=2.1'
    1 Replace <realm> with the realm where you want to authenticate the end user.
  2. View the response to see the authId and callbacks:

    Show response
    {
        "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...G6ZY_vWFpsTTaewUTVk1x4diSOpc2HK8LispKh_3nBw",
        "callbacks": [
            {
                "type": "NameCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "User Name"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken1",
                        "value": ""
                    }
                ],
                "_id": 0
            },
            {
                "type": "PasswordCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "Password"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken2",
                        "value": ""
                    }
                ],
                "_id": 1
            }
        ]
    }
  3. Submit the authId and callbacks received in the previous response, specifying the username and password of an end user in the callbacks:

    Show request
    curl \
    --request POST 'https://<tenant-name>.forgeblocks.com/am/
    json/realms/root/realms/<realm>/authenticate?authIndexType=service&authIndexValue=PasswordGrant' \ (1)
    --header 'Content-Type: application/json' \
    --header 'Accept-API-Version: resource=2.1, protocol=1.0' \
    --data-raw '{
        "authId": "<auth-id>", (2)
        "callbacks": [
            {
                "type": "NameCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "User Name"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken1",
                        "value": "<end-user-username>" (3)
                    }
                ],
                "_id": 0
            },
            {
                "type": "PasswordCallback",
                "output": [
                    {
                        "name": "prompt",
                        "value": "Password"
                    }
                ],
                "input": [
                    {
                        "name": "IDToken2",
                        "value": "<end-user-password>" (4)
                    }
                ],
                "_id": 1
            }
        ]
    }'
    1 Replace <realm> with the realm where you want to authenticate the end user.
    2 Replace <auth-id> with authID from the response in the previous step
    3 Replace <end-user-username> with an end user username
    4 Replace <end-user-password> with an end user password
  4. View the response to see the session token, represented as tokenID:

    Show response
    {
        "tokenId": "iqY2oQpz_6LgFrXa449JtLUtKXo.*AAJTSQACMDIAAlNLABx4c1JzVEdTN2l5ZVhzeWhtcTBzcXBrV1hZYkE9AAR0eXBlAANDVFMAAlMxAAIwMQ..*",
        "successUrl": "/enduser/?realm=/alpha", (1)
        "realm": "/alpha" (1)
    }
    1 The example response is from an Alpha realm request.

Use an end-user session token

To use the session token with the REST API, set it as an HTTP header value. For the HTTP header field name, use the tenant session cookie name (found in Tenant Settings > Global Settings > Cookie).

The following example uses the session token to get information about the session:

Show request
curl \
--request POST 'https://<tenant-name>.forgeblocks.com/am/
json/realms/root/realms/<realm>/sessions?_prettyPrint=true&_action=getsessioninfo' \ (1)
--header 'Accept-API-Version: resource=4.0' \
--header 'Content-Type: application/json' \
--header '<session-cookie-name>: <session-cookie>' \ (2) (3)
--data-raw ''
1 Replace <realm> with the realm where you want to authenticate the end user.
2 Replace <session-cookie-name> with the session cookie name configured for the tenant.
3 Replace <session-token> with the tokenId in the authentication response (see Get an end-user session token).
Show response
{
    "username": "ed88fc9d-2f43-4cdd-af06-403bde5cf56c",
    "universalId": "id=ed88fc9d-2f43-4cdd-af06-403bde5cf56c,ou=user,o=alpha,ou=services,ou=am-config", (1)
    "realm": "/alpha", (1)
    "latestAccessTime": "2021-07-30T18:36:02Z",
    "maxIdleExpirationTime": "2021-07-30T19:06:02Z",
    "maxSessionExpirationTime": "2021-07-30T20:36:01Z",
    "properties": {
        "AMCtxId": "1010cfb1-710a-42d2-9045-9a5672ff6d8f-105170",
        "mySessionProperty": ""
    }
}
1 The example response is from an Alpha realm request.