Tokens

API tokens authenticate requests. There are two kinds:

Secret — format avatar_<8hex>.<56hex>, carries a list of permission scopes. Used server-side; never expose it in a browser.
Publishable — format pk_<8hex>.<56hex>, locked to the session:connect scope and restricted to a list of allowed origins. Safe to embed in browser-side code (e.g. the widget).

List tokens

GET /api/v1/tokens

Returns all active (non-revoked) API tokens for the authenticated account.

Query parameters

Name	Type	Default	Description
`include_session_tokens`	boolean	`false`	Include short-lived session tokens.

Response 200

{
  "data": [
    {
      "id": "019...",
      "name": "My app",
      "token_prefix": "avatar_ab",
      "scopes": ["*"],
      "status": "active",
      "workspace_id": null,
      "kind": "secret",
      "allowed_origins": null,
      "created_at": 1719000000
    }
  ]
}

created_at is a Unix timestamp in seconds. allowed_origins is a JSON-encoded array (same shape as scopes) for publishable keys, or null for secret keys.

Create a token

POST /api/v1/tokens

Creates a new API token. The full token value is returned only in this response — it cannot be retrieved again.

Request body

{
  "name": "My app",
  "scopes": ["*"],
  "workspaceId": null
}

Field	Required	Description
`name`	Yes	Human-readable label.
`kind`	No	`"secret"` (default) or `"publishable"`.
`scopes`	No	Defaults to `["*"]` (full access). Ignored for publishable keys — always locked to `["session:connect"]`.
`allowedOrigins`	Required for publishable keys	Array of `http(s)://` origins allowed to use the key. At least one is required.
`workspaceId`	No	Scope token to a specific workspace.

Response 201

{
  "id": "019...",
  "name": "My app",
  "token": "avatar_abc12345.def6789012345678901234567890123456789012345678901234",
  "scopes": ["*"],
  "kind": "secret",
  "allowed_origins": null,
  "created_at": 1719000000
}

Creating a publishable key

Publishable keys are safe to embed in browser-side code (e.g. the widget). The server rejects the request if allowedOrigins is missing or empty (400 allowed_origins_required) or contains a malformed origin (400 invalid_origins).

{
  "name": "My Embed Key",
  "kind": "publishable",
  "allowedOrigins": ["https://example.com"]
}

Response 201

{
  "id": "019...",
  "name": "My Embed Key",
  "token": "pk_abc12345.def6789012345678901234567890123456789012345678901234",
  "scopes": ["session:connect"],
  "kind": "publishable",
  "allowed_origins": ["https://example.com"],
  "created_at": 1719000000
}

Get a token

GET /api/v1/tokens/{tokenId}

Returns a single token by its ID. Does not include the raw token value.

Revoke a token

DELETE /api/v1/tokens/{tokenId}

Permanently revokes a token. Revoked tokens are rejected immediately. This action cannot be undone.

Response 200

{
  "ok": true,
  "revoked_at": 1719000000
}

revoked_at is a Unix timestamp in seconds.