Getting an Access Token

Getting the Access Token

In order to get an Access Token, make a POST request to the token end point:

https://api.unloc.app/auth/v1/token/

Including the following three parameters inside the request's body:

  1. grant_type: Will be "client_credentials" for this case
  2. client_id: The Client ID you were provided with
  3. client_secret: The Client Secret you were also provided
  4. scope: Either "integrator.admin" or "lockHolder.admin"

Integrator Admin Scope

Here's and example of an Access Token request with the integrator.admin scope:

curl --request POST '<<api_url>>/auth/v1/token/' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "**Your Client ID**",
    "client_secret": "**Your Client Secret**",
  "scope": "integrator.admin"
}'

The response will have the following format:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibm", // shortened for simplicity. Your actual token will be longer
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": [
      "integrator.admin"
  ]
}

Lock Holder Admin Scope

The scope property can receive an array of lockHolder.admin[lockHolderId] scope strings. Te returned Access Token will provide access to all of the requested scopes. Here's an example request:

curl --location --request POST '<<api_url>>/auth/v1/token/' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "**Your Client ID**",
    "client_secret": "**Your Client Secret**"
    "scope":[
        "lockHolder.admin:5d7c7d59-dd94-4b0e-8df4-501c028e37ea",
        "lockHolder.admin:7931c050-7d14-4a21-80d0-2b8a6844d04a"
    ]
}'

The response will have the following structure:

{
    "access_token": "mV4cI6MTY1NDAzMjI3N3IiXX0m2hU91eGGWP.muTmF5eUiOiJSb2N0c0bkwVwnwcetb",
    "token_type": "bearer",
    "expires_in": 3600,
    "lock_holder_ids": [
      "5d7c7d59-dd94-4b0e-8df4-501c028e37ea",
      "7931c050-7d14-4a21-80d0-2b8a6844d04a"
    ],
    "scope": [
        "lockHolder.admin:5d7c7d59-dd94-4b0e-8df4-501c028e37ea",
        "lockHolder.admin:7931c050-7d14-4a21-80d0-2b8a6844d04a"
    ]
}

Using the Access Token

Unloc's Integrator API endpoints will validate for the presence of an Authorization header containing the value Bearer followed by a space and then the access_token received in the Token request. Here's an example:

Authorization: Bearer mV4cI6MTY1NDAzMjI3N3IiXX0m2hU91eGGWP.muTmF5eUiOiJSb2N0c0bkwVwnwcetb

Use this header when making requests to the Integrator API.

Refreshing the Token

When the token expires, you get an error response with the code 401 and the following response body:

{
    "error": "JsonWebTokenError",
    "errorDescription": "JWT expired"
}

You can catch this response and make a new request to the Auth endpoint in order to get a new Access Token and update your Bearer token on the Authorization header.

You can also calculate the expiration date/time of the Access Token by taking into account the expires_in property of the Token response to preemptively request a new Token when the lifetime of the current one is about to expire.

📘

Did you know?

You can avoid making unnecessary extra requests to the Token request endpoint by storing your access_token in memory to authenticate your requests.


What’s Next

The next step will be to use the Lock Holder Admin Access Token to query for or create Lock Holders.

Once you get a hold of your Lock Holder IDs, you can use them to generate an Lock Holder Admin Access Token and manage its Locks, Keys, Roles, and more.

Did this page help you?