How to use access tokens with API calls

This section assumes that you have retrieved an access token following the steps described in the Authentication article.

This access token is a bearer token that must be passed to any API request. The bearer token has an expiration and the authentication flow described in the previous article must be done before the expiration of the bearer token,

As explained before the Secure Token Service (STS) return this JSON payload after successful authentication.

{
  "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjIwMTgtMDEtMjYtaWFtcy1zaWduaW5nLWNyZWRlbnRpYWwiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE2NDAwMzAxMjIsImV4cCI6MTY0MDAzMzcyMiwiaXNzIjoiaHR0cHM6Ly9zdHMtZGVtby5jbGVhcmlkLmlvIiwiY2xpZW50X2lkIjoiNjYyNTIyMWYtNGU2Ni00YmM4LTgzMDUtY2I4Y2JkODdiMjFmOmNsZWFyaWRkZW1vcyIsInN1YiI6IjY2MjUyMjFmLTRlNjYtNGJjOC04MzA1LWNiOGNiZDg3YjIxZiIsImF1dGhfdGltZSI6MTY0MDAzMDEyMiwiaWRwIjoibG9jYWwiLCJlbWFpbCI6IjY2MjUyMjFmLTRlNjYtNGJjOC04MzA1LWNiOGNiZDg3YjIxZiIsInJvbGUiOiJTZXJ2aWNlIiwiYWNjb3VudF9pZCI6ImNsZWFyaWRkZW1vcyIsImNsZWFyaWRkZW1vc19zdGF0ZSI6IkFjdGl2ZSIsImNsZWFyaWRkZW1vc19yb2xlIjoiYWRtaW4iLCJjbGVhcmlkZGVtb3NfaXNfZGVsZWdhdGUiOmZhbHNlLCJqdGkiOiIwMDUwRjA3ODk2MjRCNjlGREM5NjFEMTA4QkQ1RDc3MiIsImlhdCI6MTY0MDAzMDEyMiwic2NvcGUiOlsiaWFtcy1hbGwtcGVybWlzc2lvbnMtZGVsZWdhdGVkIiwiaWFtcy1hcGkiLCJpYW1zLXJvbGVzIiwib3BlbmlkIl0sImFtciI6WyJhc3NlcnRpb24iXX0.kO3QzR9KP8pQxu4juBtpotk1Gdfpt095f9V8Xx75tW3ZzjK5kNB8ZEjJKe34p8oe_YAou_6xFL_lrIc3L0X4I9qJaV-8RDnCzyw2hWw2Vh4TGpwNgfM-BE6e7NZzfvWsmByYCrQQqLNqtKyPirjNgYeO_dLtGdfSbHpBayV7r-nuurGNAc1I0Y5wtoo6vbuKtmXCYl59mD22kYE4o2ucVtt94P8RkoXPD6eTY0TNB-C1e1IQyGrMdlqcmff9TiUhrAIwSWmxr4E-4JlYdVqahZoLSg2ZnmpnSCAnQbCy568SEa-is9WbSO2LNhsKBW7_URa7rQ2-oDyC8h2pCDFXhg",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "iams-all-permissions-delegated iams-api iams-roles openid"
}

They are two important pieces of information in this response, the access_token and the expiration.

The access_token is temporary and should never be stored, it should only be kept in memory

expires_in is the number of seconds before the tokens in invalid. The maximum ClearID allows is 3600 seconds / one hour. You must make sure to request a new access token via the token endpoints before it expires.

Calling a REST API

Let's look at how we can call the Identity API to retrieve IDs that do not match any external ID.
The Identity Service REST API requires the accountid in almost every calls.

GET /api/v2/accounts/{accountid}/identities

The AccountID is located in the JSON file download from ClearID, see the Authentication for more details on it.

In every REST call, the Authorization header must be provided and contain the valid bearer token that has been returned by the Token endpoint of the STS.

Authorization: Bearer

GET /api/v2/accounts/cleariddemos/identities
host: https://identityservice-demo.clearid.io
accept: application/json
Authorization: Bearer eyJhbGciOiJSUzUxMiIsImtpZCI6IjIwMTgtMDEtMjYtaWFtcy1zaWduaW5nLWNyZWRlbnRpYWwiLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE2NDAwMzY3MzgsImV4cCI6MTY0MDA0MDMzOCwiaXNzIjoiaHR0cHM6Ly9zdHMtZGVtby5jbGVhcmlkLmlvIiwiY2xpZW50X2lkIjoieW91ci1jbGllbnQtaWQiLCJzdWIiOiJqZG95b25AZ2VuZXRlYy5jb20iLCJhdXRoX3RpbWUiOjE2NDAwMzY3MzgsImlkcCI6ImdlbmV0ZWNpZGVudGl0eSIsImVtYWlsIjoiamRveW9uQGdlbmV0ZWMuY29tIiwicm9sZSI6IlVzZXIiLCJhY2NvdW50X2lkIjpbImFjY2Vzc3RlY2hub2xvZ3kiLCJjbGVhcmlkZGVtb3MiLCJjb2duaWJveCIsImNvZ25pYm94bG1zIiwiY3VzdG9tc29sdXRpb25zIiwiZDFjMWZ2dG5ubSIsImRldmRlbW9zIiwiZXh4b25tb2JpbCIsImZ5NnVrMG01angiLCJpcGFrcDJ3bnh6Iiwiam1mYW1pbHkiLCJtY2Nvcm1pY2twbGFjZSIsIm1pdCIsIm5hdGlvbndpZGUiLCJwdHIiLCJxYWNvZ25pYm94Iiwic2FiZWxjbyIsInNoZWxsIiwidGFycyIsInRyYWRlc2hvdyIsInViZXIiLCJ3eXh0bGx1NzI4Il0sImFjY2Vzc3RlY2hub2xvZ3lfc3RhdGUiOiJBY3RpdmUiLCJhY2Nlc3N0ZWNobm9sb2d5X2lkZW50aXR5X2lkIjoiYzZlNDczMDAtMzU3My00ZDU2LTlkMTQtNWJjMmZkZmZiZTE2IiwiYWNjZXNzdGVjaG5vbG9neV9yb2xlIjoiYWRtaW4iLCJhY2Nlc3N0ZWNobm9sb2d5X2lzX2RlbGVnYXRlIjpmYWxzZSwiY2xlYXJpZGRlbW9zX3N0YXRlIjoiQWN0aXZlIiwiY2xlYXJpZGRlbW9zX2lkZW50aXR5X2lkIjoiMzZkOGVhODktZDQ0NS00ZDBmLWI1N2EtNTk3MTYyODM2MGNlIiwiY2xlYXJpZGRlbW9zX3JvbGUiOiJhZG1pbiIsImNsZWFyaWRkZW1vc19pc19kZWxlZ2F0ZSI6ZmFsc2UsImNvZ25pYm94X3N0YXRlIjoiQWN0aXZlIiwiY29nbmlib3hfaWRlbnRpdHlfaWQiOiIwZGMxNmE3Zi0xOTc2LTRjYzYtOWIxMi05NjNlMDJhMjBiYTEiLCJjb2duaWJveF9yb2xlIjoiYWRtaW4iLCJjb2duaWJveF9pc19kZWxlZ2F0ZSI6ZmFsc2UsImNvZ25pYm94bG1zX3N0YXRlIjoiQWN0aXZlIiwiY29nbmlib3hsbXNfaWRlbnRpdHlfaWQiOiJkYWRmOGM0ZS05ZDI0LTQ3OTItODQyMS1lYjc0YjYyMDhiZDEiLCJjb2duaWJveGxtc19yb2xlIjoiYWRtaW4iLCJjb2duaWJveGxtc19pc19kZWxlZ2F0ZSI6ZmFsc2UsImN1c3RvbXNvbHV0aW9uc19zdGF0ZSI6IkFjdGl2ZSIsImN1c3RvbXNvbHV0aW9uc19pZGVudGl0eV9pZCI6IjBiZTEwMjFiLTUxMTQtNDcwOS05ZTM0LTVkNTZlZTE2NWIyOCIsImN1c3RvbXNvbHV0aW9uc19yb2xlIjoiYWRtaW4iLCJjdXN0b21zb2x1dGlvbnNfaXNfZGVsZWdhdGUiOmZhbHNlLCJkMWMxZnZ0bm5tX3N0YXRlIjoiQWN0aXZlIiwiZDFjMWZ2dG5ubV9pZGVudGl0eV9pZCI6IjRhMzZjZThhLTYzNmQtNDgzMC04Y2Q0LWQ2YmM2MGFhNjQ2MiIsImQxYzFmdnRubm1fcm9sZSI6ImFkbWluIiwiZDFjMWZ2dG5ubV9pc19kZWxlZ2F0ZSI6ZmFsc2UsImRldmRlbW9zX3N0YXRlIjoiQWN0aXZlIiwiZGV2ZGVtb3NfaWRlbnRpdHlfaWQiOiJmY2VkMGVmYi1iZWI2LTQ3ZmEtYTQ4Ni0yOTE2MzhkNjhkODIiLCJkZXZkZW1vc19yb2xlIjoiYWRtaW4iLCJkZXZkZW1vc19pc19kZWxlZ2F0ZSI6ZmFsc2UsImV4eG9ubW9iaWxfc3RhdGUiOiJBY3RpdmUiLCJleHhvbm1vYmlsX2lkZW50aXR5X2lkIjoiYzkxMjJhMzgtOTQ4Yy00OGMyLWI4MzQtMzllN2Q5ZGY4NmYyIiwiZXh4b25tb2JpbF9yb2xlIjoiYWRtaW4iLCJleHhvbm1vYmlsX2lzX2RlbGVnYXRlIjpmYWxzZSwiZnk2dWswbTVqeF9zdGF0ZSI6IkFjdGl2ZSIsImZ5NnVrMG01anhfaWRlbnRpdHlfaWQiOiI3YTgzYTg1Zi1jMDY4LTQ3ZDYtOThkNS01MjBiZjE5ZDAzMjAiLCJmeTZ1azBtNWp4X3JvbGUiOiJhZG1pbiIsImZ5NnVrMG01anhfaXNfZGVsZWdhdGUiOmZhbHNlLCJpcGFrcDJ3bnh6X3N0YXRlIjoiQWN0aXZlIiwiaXBha3Ayd254el9pZGVudGl0eV9pZCI6IjljODBkZjliLWY3MzAtNDlhYy05MTViLTEzMjY5NGNjODFmYyIsImlwYWtwMndueHpfcm9sZSI6ImFkbWluIiwiaXBha3Ayd254el9pc19kZWxlZ2F0ZSI6ZmFsc2UsImptZmFtaWx5X3N0YXRlIjoiQWN0aXZlIiwiam1mYW1pbHlfaWRlbnRpdHlfaWQiOiIyMzI2MGM2NC1kYTIzLTRmYzQtYmJhMy00NGMzMGRhOWEwYWIiLCJqbWZhbWlseV9yb2xlIjoiYWRtaW4iLCJqbWZhbWlseV9pc19kZWxlZ2F0ZSI6ZmFsc2UsIm1jY29ybWlja3BsYWNlX3N0YXRlIjoiQWN0aXZlIiwibWNjb3JtaWNrcGxhY2VfaWRlbnRpdHlfaWQiOiIyNmQ4YmZlNS1mYzdlLTRhNGYtODZhMC1jMmY3NWEyMDRkNzIiLCJtY2Nvcm1pY2twbGFjZV9yb2xlIjoiYWRtaW4iLCJtY2Nvcm1pY2twbGFjZV9pc19kZWxlZ2F0ZSI6ZmFsc2UsIm1pdF9zdGF0ZSI6IkFjdGl2ZSIsIm1pdF9pZGVudGl0eV9pZCI6IjBlNWQyMGIwLTM2NTUtNGM2My05YjBlLThjNzA2ZTQ3YzAxNiIsIm1pdF9yb2xlIjoiYWRtaW4iLCJtaXRfaXNfZGVsZWdhdGUiOmZhbHNlLCJuYXRpb253aWRlX3N0YXRlIjoiQWN0aXZlIiwibmF0aW9ud2lkZV9pZGVudGl0eV9pZCI6ImU0YzRlZDQ0LTVjYmYtNDVmOC05OTRiLTM1MTJlOTQyM2Q3ZSIsIm5hdGlvbndpZGVfcm9sZSI6ImFkbWluIiwibmF0aW9ud2lkZV9pc19kZWxlZ2F0ZSI6ZmFsc2UsInB0cl9zdGF0ZSI6IkFjdGl2ZSIsInB0cl9pZGVudGl0eV9pZCI6ImE0MGJkYzQ1LTA4MmQtNGIzZi1hNGVhLTdjODRmZDBjOTAyYiIsInB0cl9yb2xlIjoiYWRtaW4iLCJwdHJfaXNfZGVsZWdhdGUiOmZhbHNlLCJxYWNvZ25pYm94X3N0YXRlIjoiQWN0aXZlIiwicWFjb2duaWJveF9pZGVudGl0eV9pZCI6ImRkN2RjMWVhLTg2NjMtNDlmMS1iYTg1LWM0ZTgwNDJhNGIzMCIsInFhY29nbmlib3hfcm9sZSI6ImFkbWluIiwicWFjb2duaWJveF9pc19kZWxlZ2F0ZSI6ZmFsc2UsInNhYmVsY29fc3RhdGUiOiJBY3RpdmUiLCJzYWJlbGNvX2lkZW50aXR5X2lkIjoiZDEyYjk2MWUtZTE1Zi00Y2UyLTk5YTEtNjA2ZjE3MjA1NDBlIiwic2FiZWxjb19yb2xlIjoiYWRtaW4iLCJzYWJlbGNvX2lzX2RlbGVnYXRlIjpmYWxzZSwic2hlbGxfc3RhdGUiOiJBY3RpdmUiLCJzaGVsbF9pZGVudGl0eV9pZCI6IjYwMDJjZTVhLTU0YzUtNDhjZC04YzA3LWZjYjdjNzg5NDIzMyIsInNoZWxsX3JvbGUiOiJhZG1pbiIsInNoZWxsX2lzX2RlbGVnYXRlIjpmYWxzZSwidGFyc19zdGF0ZSI6IkFjdGl2ZSIsInRhcnNfaWRlbnRpdHlfaWQiOiI0YmI5YWI3OS0yMzZiLTRhZjMtYmVhZC03M2ZmODNhMDEzODUiLCJ0YXJzX3JvbGUiOiJhZG1pbiIsInRhcnNfaXNfZGVsZWdhdGUiOmZhbHNlLCJ0cmFkZXNob3dfc3RhdGUiOiJBY3RpdmUiLCJ0cmFkZXNob3dfaWRlbnRpdHlfaWQiOiIxZjBhYTc2Yy01ODZiLTQ5MWEtODM3ZC1mYzQ2Y2I0MWZiNjAiLCJ0cmFkZXNob3dfcm9sZSI6ImFkbWluIiwidHJhZGVzaG93X2lzX2RlbGVnYXRlIjpmYWxzZSwidWJlcl9zdGF0ZSI6IkFjdGl2ZSIsInViZXJfaWRlbnRpdHlfaWQiOiJhMzcyOGIyMC0xYzA3LTQ2M2QtYmJlYy03MzI1MDQ4NjNiYjkiLCJ1YmVyX3JvbGUiOiJhZG1pbiIsInViZXJfaXNfZGVsZWdhdGUiOmZhbHNlLCJ3eXh0bGx1NzI4X3N0YXRlIjoiQWN0aXZlIiwid3l4dGxsdTcyOF9pZGVudGl0eV9pZCI6IjgzZGVjZmNmLWQxNGQtNDRiZi1iODVjLTJhOGMyOTc4NTVkYiIsInd5eHRsbHU3Mjhfcm9sZSI6ImFkbWluIiwid3l4dGxsdTcyOF9pc19kZWxlZ2F0ZSI6ZmFsc2UsImp0aSI6IjYzMzkyNTlDMTFBRjE2MkRCM0M4MUQzOEM3Q0U1QzE0Iiwic2lkIjoiREE2OThDM0M4OEM5MEZGRURCM0U3NjRDNTZEMUI4QjIiLCJpYXQiOjE2NDAwMzY3MzgsInNjb3BlIjpbIm9wZW5pZCIsInByb2ZpbGUiXSwiYW1yIjpbImV4dGVybmFsIl19.cQzbyYUzNV6K_69C030TH1RuDwykPREidJiYED_xfz16tV8X0tQAw6x87rHyzXG7e9wHv6Dy0RKSmMld0c5LEKwNPXtMxdxq9NKcrR8JVlfbjbGJ7qR5oTzz1xwLzQX1wTGG0rz_ouWvBOWBJ1BIfwsnAaaD9uBJWa6dXhCpIVVGXgrGYwlifBYSUG41b1Yf3TaTISjUBeeHq6j7oEyJ_tCdrcGx4b_Nwiczbm7DCeuXDJLpjHPvRUbC3BpHA62C_Je2DLS8FFVRVFX98bvfoXermeLyYLvwhAGsgLy3DAMxos8_6zqcyqllsZ2kttDdnJvW47o6S-4ejU_YwVU50A

NB: The complete list of all API endpoints is described here: API Endpoints

Expiration of an access token

The access_token is in fact a JWT token. once decrypted (base64) it contains more information.

To find the exact expiration time of the access token, you must decode the bearer token and read the exp value, it's a Numericdate. In the bearer token provided above, the expiration is 1640033722 which is December 20, 2021 8:55:22 PM UTC

To renew the access token follow the same steps you did to initially retrieve it

{
  "nbf": 1640030122,
  "exp": 1640033722,
  "iss": "https://sts-demo.clearid.io",
  "client_id": "6625221f-4e66-4bc8-8305-cb8cbd87b21f:cleariddemos",
  "sub": "6625221f-4e66-4bc8-8305-cb8cbd87b21f",
  "auth_time": 1640030122,
  "idp": "local",
  "email": "6625221f-4e66-4bc8-8305-cb8cbd87b21f",
  "role": "Service",
  "account_id": "cleariddemos",
  "cleariddemos_state": "Active",
  "cleariddemos_role": "admin",
  "cleariddemos_is_delegate": false,
  "jti": "0050F0789624B69FDC961D108BD5D772",
  "iat": 1640030122,
  "scope": [
    "iams-all-permissions-delegated",
    "iams-api",
    "iams-roles",
    "openid"
  ],
  "amr": [
    "assertion"
  ]
}