To make API calls easily and securely, you can create personalized access tokens. Unlike typical authentication tokens, personal access tokens have no expiration duration.
To access this setting, click your account profile icon and select Profile > Personal Access Tokens.
Create a personal access token
To create a personal access token,
Enter the token name.
You can configure whether or not to require 2FA when using this token by selecting between the Ignore Two Factor Authentication and Require Two Factor Authentication drop-down options. This is applicable for endpoints that require 2FA. If 2FA is not configured in your workspace, additional authentication is not required.
Click Add.
Enter your password or 2FA code to Verify. (This is applicable if 2FA has been enabled for your workspace.)
Your access token is generated successfully. It displays your user ID and the access token.
The following screenshot shows an example:
Remember to save the user ID and access token in a safe place as you can only view it once.
You can also generate tokens using the endpoint: Generate Personal Access Token
Delete personal access token
To delete an access token,
From the Personal Access Token list, click the Delete icon against the token you choose to delete.
Then, click Delete.
Regenerate personal access token
To regenerate an existing access token,
From the Personal Access Token list, click the refresh icon against the token you choose to regenerate.
Then, click Regenerate.
Remember to update all applications that use the old value and replace it with the regenerated token.
How to use personal access tokens
When calling any endpoint that requires user authentication, you must provide two headers: x-User-Id and x-Auth-Token. Enter the personal access token as the x-Auth-Token value. With this, you can maintain a long-term connection. See Introduction to Authentication for details.
Using personal access tokens with 2FA
If your workspace has 2FA configured, follow these steps to call an endpoint that requires 2FA:
For the
x-Auth-Tokenheader field, enter a personal access token with the Require Two Factor Authentication option.You will need to add two additional headers:
x-2fa-methodandx-2fa-code. You don’t need to provide both, you can provide thex-2fa-codeonly.The 2FA headers are required to send the request to the endpoint for the first time.
For subsequent calls, these headers are not required as you are connected via the personal access token.
See Introduction to Two-Factor Authentication for details.
Using personal access tokens without 2FA
If your workspace has 2FA configured, you may want to bypass the need for additional authentication every time you call an endpoint that requires 2FA.
For the
x-Auth-Tokenheader field, enter a personal access token with the Ignore Two Factor Authentication option.Now, you don’t need to add the additional 2FA headers, and you can maintain a connection via the personal access token.
If your workspace does not have 2FA enabled, the endpoints do not require 2FA headers. Call the endpoint using the user ID and token as usual.
If your workspace has 2FA configured, you can receive a 2FA code via email, use an authenticator app, or enter your password. Check with your workspace administrator if you are not sure about the 2FA method.
Troubleshooting
Personal access tokens are removed automatically
Personal access tokens have no expiration duration. However, they can be deleted automatically in any of the following cases:
An admin deactivates the user.
An admin logs the user out of a device.
In these cases, the user’s personal access tokens are deleted and must be created again.