Getting Access

The OTA Connect API uses OAuth 2.0 bearer tokens for authenticating individual API calls, using the OAuth 2.0 client credentials flow. Each environment on OTA Connect has a client ID and secret associated with it, which can be used to obtain a bearer token that is valid for 24 hours. You’ll pass this token in the authorization header of all API calls.

Obtaining a bearer token

To obtain a bearer token, make a Client Credentials grant request. For this, you’ll need the client_id, client_secret and scope for the environment you want to access.

How can I find my client_id, client_secret and scope?

We’re working on making API credentials a bit easier to find on the portal. But for now, the easiest way to get them is via your credentials.zip file.

Switch to the environment you want to use.
Download a provisioning credential, creating a new one if you don’t already have one.

Unzip the credentials.zip file and examine the contents of treehub.json. You’ll find the client_id, client_secret and scope listed:

{
  "oauth2" : {
    "server" : "https://ota.auth.eu-west-1.amazoncognito.com/oauth2/token",
    "client_id" : "$your_client_id", (1)
    "client_secret" : "$your_client_secret", (1)
    "scope" : "$your_scope" (1)
  },
  "ostree" : {
    "server" : "https://treehub.ota.api.here.com:443/api/v3"
  }
}

Once you’ve found your client_id, client_secret and scope, you can make the grant request using cURL. Let’s store the token in an environment variable called ota_token, so that we can re-use it for the API calls in the rest of this guide:

export ota_token=$(curl -X POST https://ota.auth.eu-west-1.amazoncognito.com/oauth2/token -d "grant_type=client_credentials" -d "scope=$SCOPE" -u $CLIENT_ID:$CLIENT_SECRET | jq -r .access_token)

To quickly verify that your token is working, you can try to list your devices:

curl "https://api.ota.here.com/v1alpha/devices" -H "accept: application/json" -H "Authorization: Bearer $ota_token" | jq . (1)

1	We’re just using `jq` for formatting the output.

With your Bearer token generated, you can try out the devices endpoints.

The token will expire every 24 hours. If the current token expires, you need to request a new token to continue using the API.