šŸš€ Heads up: Our API Docs Have Moved!
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

Scope: 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.

Returns a list of Token objects

Show an access token TokensController#show

GET /api/v1/users/:user_id/tokens/:id

Scope: 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

Scope: 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

Scope: 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

Scope: 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.