🚀 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.