Authorization

For the majority of use cases and almost all API requests, the default API Key is more than sufficient. If you're using one of our SDKs, we handle the authorization for you. If you're familiar with the OAuth2 specification, our endpoints will look familiar to you —they'll work with Postman and most oauth libs. Authorization tokens follow the JWT standard with JWKS verification keys at https://account.mytiki.com/.well-known/jwks.json.

Token Grant

Use the token grant endpoint to request a new authorization token. We support 2 grant types, client_credentials and refresh_token. Please take note, the user client credentials grant does not return a refresh token —each request requires a new grant.

• Method: POST
• Endpoint: https://account.mytiki.com/api/latest/auth/token
• Format: x-www-form-urlencoded

Client Credentials

Use the client credentials grant to request a new token with scope and expiration. Our client credential grants use a namespace pattern for the client_id field to specify the token type. Please take note of the scopes available for each type, not all scopes are available to all token types.

API Key (aka User Token)

Use this grant to generate a new API Key. Useful if you have multiple applications connecting to the platform and want to implement a more granular security pattern.

Available scopes:

• account:admin - manage your profile, organization, and generate new keys

Request fields:

• grant_type - must be set toclient_credentials
• client_id - in the format of user:<user-id>, use Get Profile to get user-id
• client_secret - your API Key
• scope - a space delimited list of scopes to request
• expires - the number of seconds until the token expires, defaults to 600

Example:

curl --request POST \
     --url https://account.mytiki.com/api/latest/auth \
     --header 'accept: application/json' \
     --data-urlencode \
     "grant_type=client_credentials" \ 
     "client_id=user:<user-id>" \ 
     "client_secret=<api-key>" \ 
     "scope=account:admin" \ 
     "expires=600"

Provider Token

Use this grant to generate a new short-lived provider token. Provider tokens are used by public facing applications like websites and mobile apps, where there are no secrets. Even though we're going to use the client_secret field for API consistency, it's not an actual secret.

Available scopes:

• account:provider - used to register and list device addresses
• trail- used to submit audit trail events, like titles and licenses
• publish - used to submit new data events

Request fields:

• grant_type - must be set toclient_credentials
• client_id - in the format of provider:<provider-id>, use Get Provider to get provider-id
• client_secret - the base64 pubKey for the provider, use Get Provider to get pubKey
• scope - a space delimited list of scopes to request
• expires - the number of seconds until the token expires, defaults to 600

Example:

curl --request POST \
     --url https://account.mytiki.com/api/latest/auth \
     --header 'accept: application/json' \
     --data-urlencode \
     "grant_type=client_credentials" \ 
     "client_id=provider:<provider-id>" \ 
     "client_secret=<pub-key>" \ 
     "scope=account:provider trail publish" \ 
     "expires=600"

Address Token

Use this grant to generate a new short-lived address token. Address tokens are used by end user's devices to request headless access tokens through asymmetric signatures.

Available scopes:

• None — New to the platform and slowing rolling out.

Request fields:

• grant_type - must be set toclient_credentials
• client_id - in the format of address:<provider-id>:<address>
• client_secret - an RSA2048 signature of the address using the registered key pair
• scope - a space delimited list of scopes to request
• expires - the number of seconds until the token expires, defaults to 600

Example:

curl --request POST \
     --url https://account.mytiki.com/api/latest/auth \
     --header 'accept: application/json' \
     --data-urlencode \
     "grant_type=client_credentials" \ 
     "client_id=address:<provider-id>:<address>" \ 
     "client_secret=<signature>" \ 
     "expires=600"

Refresh Token

Use the refresh grant to issue a new token after expiration with the same claims as the initial token. Refresh tokens are always single use. Securely persist the returning refresh to continue the grant chain. All refresh tokens have an expiration date of 30 days from issuance.

Request fields:

• grant_type - must be set torefresh_token
• refresh_token - the refresh token to use.

Example:

curl --request POST \
     --url https://account.mytiki.com/api/latest/auth \
     --header 'accept: application/json' \
     --data-urlencode \
     "grant_type=refresh_token" \ 
     "refresh_token=<refresh-token>"

Response Fields

The following fields are always returned upon a successful token grant, with the exception of the refresh_token which is only returned IF a refresh token is available for the specific grant type.

• access_token - the authorization token in JWT format
• scope - the scope that was actually granted, may differ from the requested scopes
• token_type - always Bearer
• expires_in - the number of milliseconds until the token expires
• refresh_token - the refresh token in JWT format, if there is one

Token Revoke

Both API Keys (User Tokens) and Refresh Tokens support manual and immediate revocation. All other tokens are designed to be short-lived and are safe to just let expire. Token revocation requires a valid Authorization Token with the account:admin scope — aka use one of your API Keys.

• Method: POST
• Endpoint: https://account.mytiki.com/api/latest/auth/token
• Format: x-www-form-urlencoded

Request fields:

• token - optional set to the API Key you wish to revoke
• refresh_token - optional set to the refresh token you wish to revoke

Example:

curl --request POST \
     --url https://account.mytiki.com/api/latest/auth \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <api-key1>' \
     --data-urlencode \
     "token=<api-key2>" \ 
     "refresh_token=<refresh-token>"