Access Token REST API Authentication

• Authentication by service account access token
  • When should I use it
  • How to obtain service account access token
• Authentication by user access token
  • When should I use it
  • How to obtain user access token

You will need access token in order to interact with the Kaa REST API. There are two types of access tokens:

• service account access token
• user access token

Authentication by service account access token

When should I use it

• for integration of third-party or custom services with the Kaa platform
• during development as it’s the fastest way of getting access token

How to obtain service account access token

Kaa Platform has several running Keycloak instances. Each Keycloak instance hosts a specific set of tenants for balancing reason. To find out the host of Keycloak instance that hosts your tenant, go to User management -> Advanced settings. You will be end up on the Keycloak admin page. From browser URL you can find Keycloak host,

In the above case, Keycloak host is https://autha.cloud.kaaiot.com

Open terminal and initialize $KEYCLOAK_HOST with the obtained value.

export KEYCLOAK_HOST={your-keycloak-host}

Initialize $TENANT_ID (see how you can find tenant ID here):

export TENANT_ID={your-tenant-id}

From Kecyloak admin page go to Clients, search for the client with the kaa-rest-api name and copy its client ID.

Initialize $CLIENT_ID with the obtained value.

export CLIENT_ID={client-id}

Switch to the “Credentials” tab and copy Secret.

Initialize $CLIENT_SECRET with the obtained value.

export CLIENT_SECRET={client-secret}

Finally, run the following curl to get service account access token:

curl -X POST \
  $KEYCLOAK_HOST/auth/realms/$TENANT_ID/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Use the value of the access_token field as the access token by prefixing it with the bearer in requests to the Kaa platform microservices REST API.

GET /api/v1/endpoints example:

curl https://cloud.kaaiot.com/epr/api/v1/endpoints \
  -H 'Authorization: bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUI...'

{"totalElements":1,"content":[{"endpointId":"0de07db5-5d40-4108-8cf3-1aee344b4aef"...

Authentication by user access token

When should I use it

Use it in case you want your final user to authenticate himself by his own credentials - username and password. This type of authentication comes handy for mobile apps and custom UI dashboards.

How to obtain user access token

To obtain a user access token that can be used in calls to Kaa Platform REST API you will need:

• Host of Keycloak instance that hosts your tenant
• Tenant ID
• Client ID

Kaa Platform has several running Keycloak instances. Each Keycloak instance hosts a specific set of tenants for balancing reason. To find out the host of Keycloak instance that hosts your tenant, go to User management -> Advanced settings. You will be forwarded to the authentication page which URL contains Keycloak host and tenant ID.

In the above case, keycloak host is https://autha.cloud.kaaiot.com

Go to Clients, search for the client with the kaa-frontend name and copy its client ID.

From the above screen, client ID is 3b4b2a5d-1514-44eb-98c0-f4041b362e1b.

To obtain end user’s access token that can be later used in calls to Kaa REST API use the following cURL command.

curl -X POST \
  https://{keycloak-host}/auth/realms/{tenantID}/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&client_id={client_id}&username={username}&password={password}'

Let’s see how the final cURL command will look. Substitute {username} and {password} with your own. To find out {username} and {password}, go to Users -> select your user. From there you will find your username. To reset password, go to Credentials tab, enter Password, Password Confirmation, uncheck Temporary and hit Reset Password.

curl -X POST \
  https://autha.cloud.kaaiot.com/auth/realms/59433264-b474-4de1-bfe6-9c5ca3e86ddc/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&client_id=3b4b2a5d-1514-44eb-98c0-f4041b362e1b&username=admin&password=admin'

You will get long JSON output with access token after running cURL.

Use the value of the access_token field as the access token by prefixing it with the bearer in requests to the Kaa platform microservices REST API.

GET /api/v1/endpoints example:

curl https://cloud.kaaiot.com/epr/api/v1/endpoints \
  -H 'Authorization: bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUI...'

{"totalElements":1,"content":[{"endpointId":"0de07db5-5d40-4108-8cf3-1aee344b4aef"...

GET /api/v1/applications/{applicationName}/time-series/last example:

curl https://cloud.kaaiot.com/epts/api/v1/applications/c4f5gl2d4ks1slmoepa0/time-series/last \
  -H 'Authorization: bearer eyJhbGciOiJSUzI1NiIsInR5cCIg...'

{"2ebaf0ab-76f3-4211-a27f-af310be8987f":{"temperature": [...