Nurama Developers
Namespaces

token

Methods and types of the `token` namespace (`client.token` / `bot.token`).

Interfaces

CreateTokenData

Properties

PropertyTypeDescription
expiresAt?string | nullOptional ISO date. Null / omitted = non-expiring.
namestringCustomer-facing label. 1–80 characters.
scopesTokenScope[]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

PropertyTypeDescriptionInherited from
createdAtstring-TokenSummary.createdAt
expiresAt?string | null-TokenSummary.expiresAt
idstring-TokenSummary.id
kindTokenKind-TokenSummary.kind
lastUsed?string | null-TokenSummary.lastUsed
namestring-TokenSummary.name
prefixstring-TokenSummary.prefix
scopesTokenScope[]-TokenSummary.scopes
tokenstringThe 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

PropertyType
createdAtstring
expiresAt?string | null
idstring
kindTokenKind
lastUsed?string | null
namestring
prefixstring
scopesTokenScope[]

UpdateTokenScopesData

Properties

PropertyTypeDescription
scopesTokenScope[]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

ParameterType
clientdefault

Returns

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

On this page