Kaa Cloud 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

Warning: This page is dedicated to the Kaa Cloud version of the Kaa platform and does not apply to Kaa Next. If you are unsure which version of the Kaa platform you are using, see here.

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": [...