token
Methods and types of the `token` namespace (`client.token` / `bot.token`).
Interfaces
CreateTokenData
Properties
| Property | Type | Description |
|---|---|---|
expiresAt? | string | null | Optional ISO date. Null / omitted = non-expiring. |
name | string | Customer-facing label. 1–80 characters. |
scopes | TokenScope[] | At least one scope. Validated against the backend registry. |
CreateTokenResponse
The shape returned by listTokens and (without the token field)
the metadata half of createToken. Never includes the raw secret —
that is shown exactly once at creation time and is the caller's
responsibility to capture.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|---|---|---|
createdAt | string | - | TokenSummary.createdAt |
expiresAt? | string | null | - | TokenSummary.expiresAt |
id | string | - | TokenSummary.id |
kind | TokenKind | - | TokenSummary.kind |
lastUsed? | string | null | - | TokenSummary.lastUsed |
name | string | - | TokenSummary.name |
prefix | string | - | TokenSummary.prefix |
scopes | TokenScope[] | - | TokenSummary.scopes |
token | string | The raw secret. Returned ONLY in this response. The server keeps a one-way hash and cannot recover this value — the customer must capture it immediately (typical pattern: reveal-once modal with a copy button). | - |
TokenSummary
The shape returned by listTokens and (without the token field)
the metadata half of createToken. Never includes the raw secret —
that is shown exactly once at creation time and is the caller's
responsibility to capture.
Extended by
Properties
| Property | Type |
|---|---|
createdAt | string |
expiresAt? | string | null |
id | string |
kind | TokenKind |
lastUsed? | string | null |
name | string |
prefix | string |
scopes | TokenScope[] |
UpdateTokenScopesData
Properties
| Property | Type | Description |
|---|---|---|
scopes | TokenScope[] | The COMPLETE new scope set, not a delta — the same shape createToken takes, so what a token may do is always stated in full rather than accumulated through edits nobody can review. At least one scope. |
Type Aliases
TokenKind
type TokenKind = "pat" | "oauthAccess" | "oauthRefresh" | "botAccess";Personal Access Token kinds. v1 only mints pat; the rest are
reserved for the future OAuth grant flow and are listed here so
downstream code can switch on the kind without importing a server-
side enum.
TokenScope
type TokenScope =
| "chat:read"
| "chat:write"
| "tasks:read"
| "tasks:write"
| "assets:read"
| "assets:write"
| "projects:read"
| "projects:write"
| "workspaces:read"
| "workspaces:write"
| "convos:read"
| "convos:write"
| "notifications:read"
| "notifications:write"
| "ai:use";Granted action verbs on a token. Mirrors the backend's
@config/tokenScopes registry; adding a scope on the BE means
adding it here too (or callers fall back to string when they
accept arbitrary scopes from configuration).
Functions
default()
function default(client): {
createToken: Promise<CreateTokenResponse>;
deleteToken: Promise<void>;
listTokens: Promise<TokenSummary[]>;
updateTokenScopes: Promise<TokenSummary>;
};Personal Access Token surface — auth-gated, owner-scoped. Any
logged-in user can mint, list, and revoke their own tokens; there
is no admin-on-behalf surface here (admins managing bot keys do
that via the bot methods).
Parameters
| Parameter | Type |
|---|---|
client | default |
Returns
| Name | Type | Description |
|---|---|---|
createToken() | (data) => Promise<CreateTokenResponse> | Mint a new Personal Access Token for the calling user. The raw secret is in the response's token field — store it immediately, it cannot be retrieved again. |
deleteToken() | (tokenId) => Promise<void> | Revoke one of the caller's Personal Access Tokens. The revocation is immediate — the token will return 401 on the very next request. |
listTokens() | () => Promise<TokenSummary[]> | List the caller's Personal Access Tokens. Bot-access keys held by the same user (rare but possible — admin who's also a bot owner) are filtered out server-side and surface via the bot management screens instead. |
updateTokenScopes() | (tokenId, data) => Promise<TokenSummary> | Replace the scopes on one of the caller's Personal Access Tokens. scopes is the complete new set, not a delta. This exists because the scope registry grows over time: a token minted before a scope existed cannot hold it, and without this the only remedy is minting a replacement and reconfiguring everywhere the old one is used. The change takes effect on the token's very next request. Scopes remain a ceiling, never a floor — widening a token never lets it do anything its owner cannot already do. |