Introduction to the Access Token Controller REST API (2024.09)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Use this API to create an access token.

The response includes the token value. This is the only time the token value is displayed. The value must be included as a Bearer token in the Authorization HTTP header for authorization requests.

Typically, an access token has the following attributes:

• Token name—Must be unique and 5 - 25 characters long.
• Expiry string—The token lifetime. Format: *y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.
• Token type—Valid values: NORMAL | IMPERSONATED.
• Token description—Mandatory for IMPERSONATED tokens.
• Username—User name of the user on whose behalf the token is created. Mandatory for IMPERSONATED tokens.

When a username is provided for the creation of a NORMAL token, that username is ignored when calling an API. Instead, the user calling the API is authenticated.

Use this API to very if a token is valid. Pass the token value in the request body. The response shows if the token is valid, along with information about the token.

Only the token creator can verify IMPERSONATED tokens. If you do not have the Create Impersonated Token and relevant Manage Users permissions, the API returns obfuscated values.

Use this API to update some of the attributes of a specified access token. Specify the name of the token that you want to update in the path (case sensitive).

In the request body, specify the new values. You can update the following token attributes:

• tokenName—Must be 5 - 25 characters long.
• tokenDescription—For IMPERSONATED tokens this field should state the impersonation reason.
• expiryStr—Must not be in the past. Format:*y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.

Only the token creator or another privileged user can update an IMPERSONATED token. You cannot edit an expired token or set the token expiry to a time in the past.

Use this API to delete an access token. Pass the name of the token to be deleted as a path parameter. The token name is case sensitive.

A deleted token can no longer be used to access the APIs.

Only the token creator can delete a token; this means that only users with the Create Impersonated Token and relevant Manage Users permission can delete IMPERSONATED tokens.

Token rotation means that a token's value is changed, but no other properties. Pass the name of the token to be rotated as a path parameter. The token name is case sensitive.

The response contains the new token value. Make a note of the token value; this is the only time that the new value is displayed.

It is recommended to frequently rotate access tokens, but care should be exercised to not break any integrations you may have.

Use this API to get a list of all non-expired access tokens for a specified user.
You must specify either the username or the tokenCreator parameter as search criteria.
If you pass values for both parameters in the same request, the API returns a list of all non-expired tokens that match both parameters.
If you do not have the Create Impersonated Token and relevant Manage Users permissions, the API returns obfuscated values.

Tip: If you want a more fine-grained search, use /tokens/search.

Use this API to get a count of all non-expired access tokens for a specified user.
You must specify either the username or the tokenCreator parameter as search criteria.
Tip: Use this API to specify values for the pagination parameters of the /tokens API.

Get a list of all non-expired access tokens that match specified search criteria.

You must specify at least one of the following search criteria. If you pass multiple parameters as search criteria, the API returns non-expired tokens that match all parameters.

• tokenName—Search by token name. Use an asterisk (*) as placeholder for partial searches.
  
• tokenType—Either NORMAL or IMPERSONATED. If not specified, all token types will be returned.
  
• username—The email address of the user for whom the token was created.
  
• tokenCreator—The email address of the user who created the token on another user's behalf. For NORMAL tokens, username and tokenCreator must be the same. For IMPERSONATED tokens, the user firing this query must have the Create Impersonated Token permission and a Manage Users permission.
  
• expiresBefore—Specify to filter for tokens that expire before a specified interval. Can be used in conjunction with the expiresLaterThan parameter to filter for a given time range. In that case, expiresBefore must be greater than expiresLaterThan.
• expiresLaterThan—Specify to filter for tokens that expire after a specified interval. Can be used in conjunction with the expiresBefore parameter to filter for a given time range. In that case, expiresLaterThan must be less than expiresBefore.
  
• issuedBefore—Specify to filter for tokens that were issued before a specified interval.
  

If you do not have permission to view a given token, its details are returned as masked entries.

The format for expiresBefore, expiresLaterThan and issuedBefore is *y *M *d *h *m, where y=years, M=months, d=days, h=hours, m=minutes (case sensitive), and * representing any number.

In addition to the search criteria above you must also specify the following parameters:

• page—The number of the page to be returned (zero based).
  
• pageSize—The number of records returned per page.