Token Management (tokens.ts)

Reference for SveltyCMS token lifecycle — invitation tokens, identity resolution, and programmatic website API keys.

4/12/2026

3 min read

On this page

The Tokens API manages stateless authentication secrets used for both human invitation flows and programmatic machine-to-machine access. It separates temporary identity tokens from long-lived programmatic API keys.

⚡ Quick Reference

Token Type	HTTP Endpoint	Method	Local SDK Equivalent
Invitations	`/api/token`	`GET/POST`	`cms.auth.tokens`
Provider Info	`/api/get-tokens-provided`	`GET`	N/A
Website Tokens	`/api/website-tokens`	`GET/POST`	`cms.websiteTokens`
Resolve Token	`/api/token/resolve`	`POST`	`cms.auth.tokens.resolve`

1. Identity & Invitation Tokens

These tokens are used for human-centric workflows such as inviting new users to the system or password resets.

Create Token: POST /api/token/create-token — generates a high-entropy token string for a user or action. Returns 200 OK.
List Tokens: GET /api/token/list — allows admins to monitor active invitation or recovery links.
Validate Token: GET /api/token/{tokenValue} — Publicly accessible for invitations. Returns { success: true, data: { ..., valid: true } }.
Identity Resolution: POST /api/token/resolve — converts a raw token string back into its associated metadata and user context.

2. Programmatic API Tokens

Website Tokens (also known as Personal Access Tokens) are designed for long-lived, stateless access to the SveltyCMS API without requiring a standard login session.

Endpoint: /api/website-tokens

Create: POST /api/website-tokens — returns a token secret that must be stored securely.
Usage: Pass the token in the Authorization: Bearer <token> header of your API requests.
Security: Website tokens are mathematically bound to the tenantId and the creating user’s permissions.

3. Provider Configuration

Check Config: GET /api/get-tokens-provided — Returns a mapping of active OAuth/Social providers (Google, Twitch, TikTok) based on configured environment secrets.

4. The Mechanics

Storage & Security

Hashing: All tokens are hashed using SHA-256 before storage. The raw token value is only shown once during creation.
Expiry: Tokens can be issued with a specific time-to-live (TTL). Once expired, they are automatically purged by the system’s background vacuum service.
Revocation: Tokens can be invalidated instantly via the DELETE method on their respective endpoints.

sequenceDiagram participant App as External App / Script participant Tokens as Tokens Handler (tokens.ts) participant SDK as Tokens Service participant DB as Database App->>Tokens: POST /api/website-tokens (Create) Tokens->>SDK: createToken(payload) SDK->>DB: INSERT hashed_token, metadata SDK-->>App: 200 OK (Return RAW Token ONCE) App->>App: Store Token Securely App->>Tokens: GET /api/collections (with Bearer Token) Tokens->>SDK: validateToken(raw) SDK->>DB: SELECT * FROM tokens WHERE hash = ? SDK-->>App: Authorized

Documentation