Thematic API - Authentication

Thematic uses OAuth flows to authenticate users. When using the Thematic API it is necessary to have an Access Token.

  • Access Token: a token used to tell the API who you are. These are valid for 12 hours

Access tokens are only useful if using the API once. For long lived integrations it will be necessary to have a Refresh Token. A Refresh Token cannot be used to authenticate with the API but it can be used to get a new Access Token without entering your username and password.

  • Refresh Token: a token that can be used to get an Access Token. These are valid indefinitely (until they are explicitly revoked).

Generating a Refresh Token

Generating a refresh token requires the use of a username/password combination. Only admin level accounts are able to generate and use refresh tokens. If an admin account is downgraded to a user account, any refresh tokens previously generated will not work.

THIS REFRESH TOKEN SHOULD BE KEPT SECURELY. IT CAN BE USED TO ACCESS THE SERVICE ON YOUR BEHALF.

An example using curl is shown below

curl --request POST \
--url 'https://thematic.auth0.com/oauth/token' \
--header 'content-type: application/json' \
--header 'User-agent: NAME_FOR_INTEGRATION' \
--data \
'{ 
    "grant_type":"password",
    "username":YOUR_USERNAME,
    "password":YOUR_PASSWORD,
    "client_id": "xWZDgSXfg1NfmBarxyIwJD5btukjx1tk",
    "audience": "https://client.getthematic.com/api",
    "scope": "openid offline_access"
}'

The parameters you will need to fill in are:

  • NAME_FOR_INTEGRATION: This is anything that will help you identify the refresh token later
  • YOUR_USERNAME: your username
  • YOUR_PASSWORD: your password

This will return a json block which, if successful will include 'refresh_token'.

Using a Refresh Token

A refresh token can be used to 'swap' for an access token. This is the main purpose of a refresh token.

An example using curl is shown below

curl --request POST \
--url 'https://thematic.auth0.com/oauth/token' \
--header 'content-type: application/json' \
--data \
'{
     "grant_type":"refresh_token",
     "refresh_token":REFRESH_TOKEN,
     "client_id": "xWZDgSXfg1NfmBarxyIwJD5btukjx1tk",
     "audience": "https://client.getthematic.com/api",
     "scope": "openid offline_access"
}'

The parameters you will need to fill in are:

  • REFRESH_TOKEN: the token as returned above as a string

This will return a json block which, if successful will include 'access_token'.

Using an Access Token

An access token is used to identify you in any calls to our API. 

The access token should be included as a header on any subsequent request to the API. This is a bearer token so should have 'bearer ' prefixed (note the space). For example, to list information about the organization you belong to: 

curl --url 'https://client.getthematic.com/api/organization' --header 'Authorization: bearer ACCESS_TOKEN'

The parameters you will need to fill in are:

  • ACCESS_TOKEN: the access token as returned above. Please note you need to add the 'bearer ' before it as in the