We have relocated to Instructure Developer Documentation Portal. š Please update your bookmarks. This page will automatically redirect after July 1, 2026.
Access Tokens API
A Token object looks like:
{
// The internal database ID of the token.
"id": null,
// The time the token was created.
"created_at": null,
// The time the token will permanently expire, or null if it does not
// permanently expire.
"expires_at": null,
// The current state of the token. One of 'active', 'pending', 'disabled', or
// 'deleted'.
"workflow_state": null,
// Whether the token should be remembered across sessions. Only applicable for
// OAuth tokens.
"remember_access": null,
// The scopes associated with the token. If empty, there are no scope
// limitations.
"scopes": null,
// If the token was created while masquerading, this is the ID of the real user.
// Otherwise, null.
"real_user_id": null,
// The actual access token. Only included when the token is first created.
"token": null,
// A short, unique string that can be used to look up the token.
"token_hint": null,
// The ID of the user the token belongs to.
"user_id": null,
// The purpose of the token.
"purpose": null,
// If the token was created by an OAuth application, this is the name of that
// application. Otherwise, null.
"app_name": null,
// Whether the current user can manually regenerate this token.
"can_manually_regenerate": null
}
List access tokens for a user TokensController#user_generated_tokens
GET /api/v1/users/:user_id/user_generated_tokens
url:GET|/api/v1/users/:user_id/user_generated_tokens
Returns a list of manually generated access tokens for the specified user. Note that the actual token values are only returned when the token is first created.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
per_page | integer |
The number of results to return per page. Defaults to 10. Maximum of 100. |
Show an access token TokensController#show
GET /api/v1/users/:user_id/tokens/:id
url:GET|/api/v1/users/:user_id/tokens/:id
The ID can be the actual database ID of the token, or the ātoken_hintā value.
Create an access token TokensController#create
POST /api/v1/users/:user_id/tokens
url:POST|/api/v1/users/:user_id/tokens
Create a new access token for the specified user. If the user is not the current user, the token will be created as āpendingā, and must be activated by the user before it can be used.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
token[purpose] | Required | string |
The purpose of the token. |
token[expires_at] | DateTime |
The time at which the token will expire. |
|
token[scopes][] | Array |
The scopes to associate with the token. Ignored if the default developer key does not have the āenable scopesā option enabled. In such cases, the token will inherit the userās permissions instead. |
Update an access token TokensController#update
PUT /api/v1/users/:user_id/tokens/:id
url:PUT|/api/v1/users/:user_id/tokens/:id
Update an existing access token.
The ID can be the actual database ID of the token, or the ātoken_hintā value.
Regenerating an expired token requires a new expiration date.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
token[purpose] | string |
The purpose of the token. |
|
token[expires_at] | DateTime |
The time at which the token will expire. |
|
token[scopes][] | Array |
The scopes to associate with the token. |
|
token[regenerate] | boolean |
Regenerate the actual token. |
Delete an access token TokensController#destroy
DELETE /api/v1/users/:user_id/tokens/:id
url:DELETE|/api/v1/users/:user_id/tokens/:id
The ID can be the actual database ID of the token, or the ātoken_hintā value.