Thematic Client API

SDK

A Python SDK is available which wraps the authorization process and most common use cases for the API. This can be found on Github

Authorization

Thematic uses Auth0 as a third party user management platform. This means that generating access tokens must use their endpoints.

The normal use of this API is to generate a refresh token once and store this securely. This refresh token is then swapped for a short lived access token each time the API is used.

Refresh Tokens

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"}'

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

The parameters to this request are required because of the authorization provider we use.

Access Tokens

While it is possible to generate an access token directly, normal use of the API would dictate the use of a refresh token so that is what is described here.

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"}'

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

Using an Access Token

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'

Revoking a Refresh Token

If a refresh token is accidentally shared, or an integration is no longer needed it is strongly suggested that you revoke the token.

To revoke a refresh token you can use the settings page on client.getthematic.com or the 'API Auth' endpoints listed below.