Skip to content

Access Tokens API

Access tokens provide persistent API authentication that does not expire unless explicitly revoked. Use them for automated scripts, integrations, and service accounts that need to call the Canvus API without interactive sign-in.

Each token is scoped to a specific user -- API calls made with a token inherit that user's permissions and identity.

Key behavior:

  • The plain-text token value is returned only at creation time. It cannot be retrieved afterward. Store it securely.
  • Tokens never expire on their own. Revoke them with the delete endpoint when no longer needed.
  • Regular users can manage their own tokens. Administrators can manage tokens for any user.

Authentication: All endpoints require authentication via Private-Token header or session cookie.

Token object

When listing or retrieving tokens, the response includes metadata but not the token value itself.

Fields:

  • id (string) -- unique token identifier (a base64-encoded hash)
  • description (string) -- human-readable description of the token's purpose
  • created_at (string) -- ISO 8601 timestamp of when the token was created

Example:

{
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp",
  "description": "CI pipeline automation",
  "created_at": "2025-03-15T09:30:36.025"
}

When a token is first created, the response also includes:

  • plain_token (string) -- the actual token value to use in the Private-Token header. Only returned once.

List Tokens

Returns all access tokens for a user. The actual token values are not included.

GET /api/v1/users/:user_id/access-tokens

Authentication: Required. Regular users can only list their own tokens. Admins can list any user's tokens.

Streaming: Supports ?subscribe for live updates.

Path parameters:

  • user-id (integer, required) -- the ID of the user whose tokens to list

Query parameters:

  • subscribe (boolean, optional) -- if true, keeps the connection open and streams updates as newline-delimited JSON
curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/users/1002/access-tokens

Response (200 OK):

[
  {
    "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp",
    "description": "CI pipeline automation",
    "created_at": "2025-03-15T09:30:36.025"
  },
  {
    "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi44SUR3aHJaY2E1UUVaOGZUeTRDejB2ZnQzWGovclQ2",
    "description": "Monitoring dashboard",
    "created_at": "2025-03-20T14:15:22.891"
  }
]

Error responses:

  • 403 Forbidden -- non-admin trying to list another user's tokens
  • 404 Not Found -- no user with the given ID exists

Get Single Token

Returns metadata for a specific access token.

GET /api/v1/users/:user_id/access-tokens/:token_id

Authentication: Required. Regular users can only view their own tokens.

Streaming: Supports ?subscribe for live updates.

Path parameters:

  • user-id (integer, required) -- the ID of the user
  • token-id (string, required) -- the ID of the token

Query parameters:

  • subscribe (boolean, optional) -- if true, keeps the connection open and streams updates as newline-delimited JSON
curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/users/1002/access-tokens/JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp

Response (200 OK):

{
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp",
  "description": "CI pipeline automation",
  "created_at": "2025-03-15T09:30:36.025"
}

Error responses:

  • 403 Forbidden -- non-admin trying to view another user's token
  • 404 Not Found -- user or token does not exist

Create Token

Creates a new access token. The response includes the plain_token field containing the actual token value. This is the only time the token value is returned -- store it securely.

POST /api/v1/users/:user_id/access-tokens

Authentication: Required. Regular users can only create tokens for themselves.

Streaming: Not supported.

Path parameters:

  • user-id (integer, required) -- the ID of the user to create a token for

Request body (JSON):

  • description (string, required) -- a human-readable label describing the token's intended use
curl -X POST \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Nightly backup script"}' \
  https://canvus.example.com/api/v1/users/1002/access-tokens

Response (201 Created):

{
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5uZXd0b2tlbklEaGVyZTEyMzQ1Njc4OTBhYmNkZWZn",
  "description": "Nightly backup script",
  "created_at": "2025-03-28T16:45:10.332",
  "plain_token": "QbhGvPSeh0hLSgfJb120I6by4ao1J5RRd59XmNOQq2g"
}

Use the plain_token value as the Private-Token header in subsequent API requests:

curl -H "Private-Token: QbhGvPSeh0hLSgfJb120I6by4ao1J5RRd59XmNOQq2g" \
  https://canvus.example.com/api/v1/users

Error responses:

  • 400 Bad Request -- missing description field
  • 403 Forbidden -- non-admin trying to create a token for another user
  • 404 Not Found -- no user with the given ID exists

Update Token Description

Changes the description of an existing access token. The token value itself is not affected.

PATCH /api/v1/users/:user_id/access-tokens/:token_id

Authentication: Required. Regular users can only update their own tokens.

Streaming: Not supported.

Path parameters:

  • user-id (integer, required) -- the ID of the user
  • token-id (string, required) -- the ID of the token

Request body (JSON):

  • description (string, required) -- the new description
curl -X PATCH \
  -H "Private-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Nightly backup script (production server)"}' \
  https://canvus.example.com/api/v1/users/1002/access-tokens/JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp

Response (200 OK):

{
  "id": "JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp",
  "description": "Nightly backup script (production server)",
  "created_at": "2025-03-15T09:30:36.025"
}

Error responses:

  • 400 Bad Request -- missing description field
  • 403 Forbidden -- non-admin trying to update another user's token
  • 404 Not Found -- user or token does not exist

Delete Token (Revoke)

Permanently revokes an access token. Any API call using this token will fail immediately after deletion.

DELETE /api/v1/users/:user_id/access-tokens/:token_id

Authentication: Required. Regular users can only delete their own tokens.

Streaming: Not supported.

Path parameters:

  • user-id (integer, required) -- the ID of the user
  • token-id (string, required) -- the ID of the token to revoke
curl -X DELETE \
  -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/users/1002/access-tokens/JDJhJDA0JENKTWJDT0g1QVNYSkFQTXh3NlhNWi5CWjlqT05yR2h0cXJ1d1VQZW9sZWlsWkJneXRXbTRp

Response (200 OK): Empty body on success.

Error responses:

  • 403 Forbidden -- non-admin trying to delete another user's token
  • 404 Not Found -- user or token does not exist