Thrill-ID: Authenticating

In order to communicate with most APIs within the ThrillTech system you will need an authenticated token issued by Thrill-ID.

This section assumes that you have either been provided an account or have created an account as shown in the previous section.

Once you have the username and password for a valid account created in Thrill-ID, you will need the authenticate that account with Thrill-ID to retrieve a Bearer token for future use.

Example: Authenticating

In this example, we will assume that you have created an account with the following credentials:

username: "example-account@yourorg.com"
password: "some_really_random_password"

In order to authenticate with Thrill-ID and retrieve the account's token for use with other APIs, you need to make a call to POST /accounts/auth. For example, if the Thrill-ID service is hosted at https://thrillid.yourorg.com, the call would look like this:

  • Request: POST https://thrillid.yourorg.com/accounts/auth
  • Content-Type: application/json
  • Body:
{
	"username": "example-account@yourorg.com",
	"password": "some_really_random_password"
}

Upon successful authentication, the response will look as follows (although the value of the tokens and access entities will be probably be different):

{
    "token": "eyJhbGciOiJIUzI1NiJ9...KydTfNYUSZFDEVNrQnWtKXNX_QYJ46RHn9tLu9qu5n",
    "refresh_token": "eyJhbGciOiJUzI1NiJ9...4lsmg2MWa3TGh6J_g51Q",
    "access_to": {
        "org_id": "thrilltech",
        "unit_ids": [
            "brand1",
            "brand2",
        ]
    }
}

Response Details

Field nameDescription
tokenThe Bearer token that should be used on all API calls. This must be passed in the Authorization header
refresh_tokenEach token for a User account has a default lifetime of 1800s (30 minutes). If the token expires, you can refresh it using this refresh_token
access_to.org_idThe organisation that this account has access to
access_to.unit_idsThe organisational units (or brands) that this account has access to

Using the Bearer Token

Once you have authenticated with Thrill-ID, you can pass the received token to future API calls within the ThrillTech system by setting the Authorization header to contain the token as a Bearer token, for example:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...KydTfNYUSZFDEVNrQnWtKXNX_QYJ46RHn9tLu9qu5n

Refreshing tokens

To refresh a token for a User account, you can use the POST /accounts/refresh endpoint. Simply pass in the current token and refresh_token that you received from the initial authentication call and you will receive updated, valid tokens:

Example

  • Request: POST https://thrillid.yourorg.com/accounts/refresh
  • Content-Type: application/json
  • Body:
{
	"token": "eyJhbGciOiJIUzI1NiJ9...KydTfNYUSZFDEVNrQnWtKXNX_QYJ46RHn9tLu9qu5n",
	"refresh_token": "eyJhbGciOiJUzI1NiJ9...4lsmg2MWa3TGh6J_g51Q"
}

If successful, the response will be the same as when you authenticated (just with new tokens):

{
    "token": "eyJhbGciOiJIUzI1NiJ9...KydTfNYUSZFDEVNrQnWtKXNX_QYJ46RHn9tLu9qu5n",
    "refresh_token": "eyJhbGciOiJUzI1NiJ9...4lsmg2MWa3TGh6J_g51Q",
    "access_to": {
        "org_id": "thrilltech",
        "unit_ids": [
            "brand1",
            "brand2",
        ]
    }
}