Authentication

Authentication and access to the API is performed via bearer authentication. When making an API request, your bearer authentication token must be provided in the Authorization header in the following format or the request will fail:

Authorization: Bearer <token>

Your bearer authentication is given in the form of a user app token that is a 48-character-long string.
Please see the ‘How is access to the API granted?’ FAQ on the Support page.

A user app token can be generated in two ways, depending on whether you are:

  • Generating one for a logged-in user, or 
  • Generating one for a non-interactive user who will not be logging into the platform (therefore the non-interactive user will be only accessing, and working with, the API)

Generating a user app token for a logged-in user

Note: Steps 1-3 need to be completed by a Global User Admin. Step 4 onwards needs to be completed by the logged-in user who has been given the ‘Developer’ role.

1. Click on Access Management in the left-hand navigation panel.

A screenshot showing the Access Management panel in the user interface

2. Click on the desired user to open their ‘User Details’ panel. 

3. In the 'User Details' panel, click 'Roles', tick Developer and click Save.

A screenshot of the 'Roles' panel

4. The logged-in user now needs to click on My profile in the bottom-left corner of the app.

A screenshot of the 'my profile' button

5. In the ‘My Details’ panel, they need to click to open the User App Tokens section and then click CREATE USER APP TOKEN.

A screenshot of the 'create user app token' button

6. In the ‘New User App Token’ modal, they need to fill in the ‘Label’ field and click + CREATE

A screenshot of the New User App Token interface

A user app token is created, accompanied by a success message in the bottom right of your screen (the token might not be created instantly, there may be a small delay). The token will only display once. They need to make sure they copy it before clicking > CONTINUE (after which it will never appear again)

A screenshot of the New User App Token results page

Note: In addition to having the ‘Developer’ role, logged-in users will also need specific roles assigned to them to enable them to execute specific types of API calls. For example, having the ‘Developer’ role and the ‘Global User Admin’ role assigned means individuals can execute Global User Admin calls via the API. This also applies to non-interactive users.

Generating a user app token for a non-interactive user

A non-interactive user is a user who does not log into the platform; they only access, and work with, the API.

1. Click on Access Management in the left-hand navigation panel.

A screenshot showing the Access Management panel in the user interface

2. Click + in the bottom right-hand corner to create a new non-interactive user.

A screenshot of the plus button from the cutover interface

3. In the ‘New User’ modal, add a first name, last name and email (username) in the required fields.

A screenshot of the 'new user' section from the cutover interface

Note that, while the email address should be in a valid email format (for example anotheruser@thisdomain.com), it does not have to belong to a genuine email account. This is because the non-interactive user will not be logging into the platform.

4. Under ‘Roles’, tick Developer.

5. Under ‘Login option’, click Non interactive.

6. Click + Create.

A screenshot of the 'new user' section from the cutover interface

A non-interactive user is created, accompanied by a success message in the bottom right of your screen.

7. From the ‘Users’ list, click on the newly created non-interactive user to open the ‘User Details’ panel.

A screenshot of the 'user details' section from the cutover interface

8. Click User App Tokens and then click CREATE USER APP TOKEN.

A screenshot of the 'create user app token' button

9. In the ‘New User App Token’ modal, fill in the ‘Label’ field and click + CREATE.

A screenshot of the 'create user app token' interface

A user app token is created, accompanied by a success message in the bottom right of your screen (the token might not be created instantly, there may be a small delay). The token will only display once. Make sure you copy it before clicking > CONTINUE (after which it will never appear again).

A screenshot of the 'create user app token' results screen

Note: User app tokens can be set to expire after a defined period of time. For guidance on setting up expiry for user app tokens, contact your Customer Success Manager (CSM). When generating and providing a user app token, make sure you let the recipient know if, and when, it is due to expire. 

Note: Whenever you generate a user app token, make sure you store it somewhere secure. Do not share it in publicly accessible places such as GitHub.

Revoking API access

1. A logged-in user needs to access the ‘My Details’ panel (as outlined in the user app token generation guidance above). For a non-interactive user, a Global User Admin needs to click on Access Management in the left-hand navigation panel and click on the desired user to open their ‘User Details’ panel. 

2. Click User App Tokens.

3. Click the bin icon next to the desired user app token.

A screenshot of the 'revoke user app token' interface

4. Click REVOKE in the ‘Revoke User App Token’ modal. This user app token will no longer be able to authenticate to the API.

A screenshot of the 'revoke user app token' interface