Using access tokens with API calls

Access tokens are security credentials used by Genetec ClearID™'s API to authenticate users and authorize access for a set amount of time. With an access token, users' information is protected through encryption for each renewed call to the API.

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 bearer token expires.

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

json

{
  "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 token becomes invalid. The maximum that ClearID allows is 3,600 seconds, or 1 hour. Make sure to request a new access token through the token endpoints before it expires.

Calling a REST API

Here is 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 call.

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

The AccountID is located in the JSON file downloaded from ClearID. See the Authentication for more details.

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

Authorization: Bearer

json

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, which is 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.

Decoded bearer token

json

{
  "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"
  ]
}