3. 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 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), or
- Generating one for a logged-in user
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.
2. Click + in the bottom right-hand corner to create a new non-interactive user.
3. In the New User modal, add a first name, last name and email (username) in the required fields.
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 along with any other required roles. In addition to having the ‘Developer’ role, non-interactive users will need specific roles assigned to them to enable them to execute specific types of API calls. For example, having the ‘Developer’ role and the ‘Workspace manager’ role assigned (along with the specific workspace/s) means individuals can execute API calls associated with the workspace manager role.
5. Under Login option, click Non Interactive.
6. Click + Create.
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.
8. Click User App Tokens and then click CREATE USER APP TOKEN.
9. In the New User App Token modal, fill in the Label field and click + CREATE.
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).
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.
Generating a user app token for a logged-in user
Important: User app tokens generated for a logged-in user will not authenticate if the user's password has expired. To avoid this from happening, we recommend generating user app tokens via a non-interactive account.
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.
2. Click on the desired user to open their User Details panel.
3. In the User Details panel, click Roles, tick Developer along with any other required roles, and click save. In addition to having the ‘Developer’ role, logged-in users will need specific roles assigned to them to enable them to execute specific types of API calls. For example, having the ‘Developer’ role and the ‘Workspace manager’ role assigned (along with the specific workspace/s) means individuals can execute API calls associated with the workspace manager role.
4. The logged-in user now needs to click on My Profile in the bottom-left corner of the app.
5. In the My Details panel, they need to click to open the User App Tokens section and then click Create User App Token.
6. In the Create User App Token modal, they need to fill in the Label field and click + Create.
A user app token is created (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).
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.
4. Click REVOKE in the Revoke User App Token modal. This user app token will no longer be able to authenticate to the API.
