Access tokens

The access tokens API allows you to list, create, modify, and delete access tokens programmatically.

When using access tokens to manage access tokens, the following restrictions apply:

  • Personal tokens can see all service tokens and other personal tokens created by the same team member. If the personal token has the "Admin" role, it may also see other member's personal tokens. To learn more, read Personal tokens.
  • Service tokens can see all service tokens. If the token has the "Admin" role, it may also see all personal tokens. To learn more, read Service tokens.
  • Tokens can only manage other tokens, including themselves, if they have "Admin" role or explicit permission via a custom role. To learn more, read Personal access token actions.

Several of the endpoints in the access tokens API require an access token ID. The access token ID is returned as part of the Create access token and List access tokens responses. It is the _id field, or the _id field of each element in the items array.

To learn more about access tokens, read API access tokens.

List access tokens

Fetch a list of all access tokens.

Request
query Parameters
showAll
boolean

If set to true, and the authentication access token has the 'Admin' role, personal access tokens for all members will be retrieved.

limit
integer <int64>

The number of access tokens to return in the response. Defaults to 25.

offset
integer <int64>

Where to start in the list. This is for use with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

Responses
200

Access tokens collection response

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/tokens
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalCount": 0
}
Create access token
Create a new access token.


Request 
Request Body schema: application/json
required
name
string
A human-friendly name for the access token


 
description
string
A description for the access token


 
role
string
Built-in role for the token


 Enum: "reader" "writer" "admin"  
customRoleIds
Array of strings
A list of custom role IDs to use as access limits for the access token


 
Array of objects (StatementPost) 
A JSON array of statements represented as JSON objects with three attributes: effect, resources, actions. May be used in place of a built-in or custom role.


 
serviceToken
boolean
 
defaultApiVersion
integer
The default API version for this token


 
Responses 
201
Access token response


400
Invalid request


401
Invalid access token


403
Forbidden


429
Rate limited


post/api/v2/tokens
Request samples 
application/json
{
  • "role": "reader"
}
Response samples 
application/json
{
  • "_id": "string",
  • "ownerId": "string",
  • "memberId": "string",
  • "_member": {
    },
  • "name": "Example reader token",
  • "description": "A reader token used in testing and examples",
  • "creationDate": 0,
  • "lastModified": 0,
  • "customRoleIds": [ ],
  • "inlineRole": [ ],
  • "role": "reader",
  • "token": "1234",
  • "serviceToken": false,
  • "_links": {
    },
  • "defaultApiVersion": 20220603,
  • "lastUsed": 0
}
Get access token
Get a single access token by ID.


Request 
path Parameters
id
required
string <string> 
The ID of the access token


 
Responses 
200
Access token response


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


get/api/v2/tokens/{id}
Request samples 
Response samples 
application/json
{
  • "_id": "string",
  • "ownerId": "string",
  • "memberId": "string",
  • "_member": {
    },
  • "name": "Example reader token",
  • "description": "A reader token used in testing and examples",
  • "creationDate": 0,
  • "lastModified": 0,
  • "customRoleIds": [ ],
  • "inlineRole": [ ],
  • "role": "reader",
  • "token": "1234",
  • "serviceToken": false,
  • "_links": {
    },
  • "defaultApiVersion": 20220603,
  • "lastUsed": 0
}
Patch access token
Update an access token's settings. Updating an access token uses a JSON patch representation of the desired changes. To learn more, read Updates.


Request 
path Parameters
id
required
string <string> 
The ID of the access token to update


 
Request Body schema: application/json
required
 Array 
op
required
string
The type of operation to perform


 
path
required
string
A JSON Pointer string specifying the part of the document to operate on


 
value
any
A JSON value used in "add", "replace", and "test" operations


 
Responses 
200
Access token response


400
Invalid request


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


409
Status conflict


422
Invalid patch content


429
Rate limited


patch/api/v2/tokens/{id}
Request samples 
application/json
[
  • {
    }
]
Response samples 
application/json
{
  • "_id": "string",
  • "ownerId": "string",
  • "memberId": "string",
  • "_member": {
    },
  • "name": "Example reader token",
  • "description": "A reader token used in testing and examples",
  • "creationDate": 0,
  • "lastModified": 0,
  • "customRoleIds": [ ],
  • "inlineRole": [ ],
  • "role": "reader",
  • "token": "1234",
  • "serviceToken": false,
  • "_links": {
    },
  • "defaultApiVersion": 20220603,
  • "lastUsed": 0
}
Delete access token
Delete an access token by ID.


Request 
path Parameters
id
required
string <string> 
The ID of the access token to update


 
Responses 
204
Action succeeded


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


delete/api/v2/tokens/{id}
Request samples 
Response samples 
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}
Reset access token
Reset an access token's secret key with an optional expiry time for the old key.


Request 
path Parameters
id
required
string <string> 
The ID of the access token to update


 
query Parameters
expiry
integer <int64> 
An expiration time for the old token key, expressed as a Unix epoch time in milliseconds. By default, the token will expire immediately.


 
Responses 
200
Access token response


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


post/api/v2/tokens/{id}/reset
Request samples 
Response samples 
application/json
{
  • "_id": "string",
  • "ownerId": "string",
  • "memberId": "string",
  • "_member": {
    },
  • "name": "Example reader token",
  • "description": "A reader token used in testing and examples",
  • "creationDate": 0,
  • "lastModified": 0,
  • "customRoleIds": [ ],
  • "inlineRole": [ ],
  • "role": "reader",
  • "token": "1234",
  • "serviceToken": false,
  • "_links": {
    },
  • "defaultApiVersion": 20220603,
  • "lastUsed": 0
}
➔ Next to Account members