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

With the exception of the public validation route, every token route above requires an admin session or the mapped api:token permission (Website Tokens stay strictly admin-only). Unauthenticated GET /api/token/{value} now returns 401.

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/validate-token/{tokenValue} — the only public token route (invitation links). Returns { success: true, data: { ..., valid: true } }. The legacy GET /api/token/{tokenValue} alias now requires an authenticated session and additionally passes the dispatcher’s system:read gate plus the handler’s admin / api:token check, and all token mutations (PUT/DELETE/create-token/batch) require admin or the mapped api:token permission.
• 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: Website tokens / share links are hashed with unsalted SHA-256 (hashCredentialSha256Hex) before storage — sound for equality lookup of high-entropy CSPRNG values. Programmatic sck_* API keys use HMAC-SHA-256 keyed with the instance secret (hashApiKey(), derived from JWT_SECRET_KEY) so a leaked database alone is not brute-forceable. In both cases the raw 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.
• Authorization & field allowlist: /api/token/* is a positive allowlist — only GET /api/token/validate-token/{value} is public. PUT /api/token/{id} accepts expires, blocked and consumed (admins additionally email, role); user_id, type, token, _id and tenantId are never client-writable.

Related Documents

• Authentication & Identity (auth.ts)
• System Reference (system.ts)
• SCIM 2.0 (scim.ts)
• Secrets & Tokens Inventory — where every token and secret lives in the system