Get Access Tokens

You will need to request an access token to be able to use Harbor API’s.

Scopes

Different scopes are required to communicate with the different API’s:

- The scope service_provider is required to communicate with the service provider API: https://api.harborlockers.com/docs,

The resulting token is for your backend only.

- The scope tower_access is for the SDK to be able to communicate with the SDK API https://api.harborlockers.com/sdk/docs .

This token is for your mobile application.

What environment should I use?

In order to find out which environment your tower should be using, check your tower ID.

The first 2 numbers will tell you which environment your tower is configured to.

10 - production
01 - sandbox

For this we’ll select the client_credentials grant type. Let’s get an access token for our backend application, with scope service_provider

For production the URL to request our access tokens it is

https://accounts.harborlockers.com/realms/harbor/protocol/openid-connect/token

For sandbox

https://accounts.sandbox.harborlockers.com/realms/harbor/protocol/openid-connect/token

Tip

This Url will be referred to as {accounts_url} on the rest of this page. Don’t send any requests without replacing any variables in curly brackets {} with actual data

Example requests

Using the proper url, you can make your request for client credentials like this.

$ curl -X 'POST' \
    '{accounts_url}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&scope=service_provider&client_id={your client id}&client_secret={your client secret}'

Here’s a node.js request from our example webapp

app.post("/access-token", async (req, res) => {
console.log("access-token route hit");

const bodyParams = new URLSearchParams({
    grant_type: "client_credentials",
    scope: "service_provider",
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
});

try {
    const response = await fetch(Access_token_url, {
        method: "POST",
        headers: {
            accept: "application/json",
            "Content-Type": "application/x-www-form-urlencoded",
        },
        body: bodyParams.toString(),
    });
    const data = await response.json();
    token = data.access_token;
    console.log("token is", token);
    res.json(data);
} catch (err) {
    res.status(500).json({ error: err.message });
    }
});

the response will look like this:

{
    "access_token": "Your access token will be a very long string",
    "refresh_token": null,
    "refresh_expires_in": 0,
    "expires_in": 300,
    "token_type": "Bearer"
}

Now to get a mobile SDK token the flow is the same but request scope tower_access instead of service_provider.

 $ curl -X 'POST' \
'{accounts_url}' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=tower_access&client_id={your_client_id}&client_secret={your_client_secret}'

Refreshing the token

If at any point your token has expired you can use the following code to refresh it.

 curl -X 'POST' \
'{accounts_url}' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token&client_id=your client id&client_secret={your client secret}&refresh_token={your very long token here}'

Testing your SDK token

If you need to test your token you can use the api url.

Remember to change the url if you are using the test environment:

https://api.sandbox.harborlockers.com/api/v1/login/test-token

$ curl -X 'POST' \
'https://api.harborlockers.com/api/v1/login/test-token' \
-H 'accept: application/json' \
-H 'Authorization: Bearer your very long access token...' \
-d ''

Your response will look something like:

{"email":"test@test.com","isActive":true,"isSuperuser":true,
"fullName":"name","emailValidated":true,"status":null,
"id":"0dab72be57ba56","createdAt":"2023-09-26T17:27:52.889000",
"updatedAt":null,"role":1,"clientId":"client_id","appSettings":null}%

If instead your response is an error:

A 401 error means you should check your credentials and environment. If these are fine, request a new token as yours might have expired.

A 404 error means you should check your url for typos.

For our typical app flow, go to Discover Towers

For advanced users and special circumstances, try SDK tools