Keys, credits and account routes
Sign-in, API keys, credits, purchases, account usage, downloads and health.
Auth and keys
GET /api/v1/auth/login
Starts Thundera SSO. Redirects to auth.thundera.eu and back to the callback.
- Auth
- None
- Body / query
- Query:
redirect(same-site path) - Response
- 302
- Errors
- —
GET /api/v1/auth/callback
SSO return. Sets the swarm_session cookie and redirects into the app.
- Auth
- None
- Body / query
- Query from the auth service
- Response
- 302
- Errors
- 401
GET /api/v1/auth/me
The current user and roles.
- Auth
- Session or API key
- Body / query
- —
- Response
{user:{id, email, name, roles}}- Errors
- 401
POST /api/v1/auth/logout
Revokes the Swarm-local session.
- Auth
- Session or API key
- Body / query
- —
- Response
{ok:true}- Errors
- —
POST /api/v1/auth/session-refresh
Re-issues swarm_session after the Thundera token rotated. The web app calls it on a 401 and retries.
- Auth
- Thundera cookies
- Body / query
- —
- Response
{ok:true}plus a new cookie- Errors
- 401
POST /api/v1/auth/device-key
Exchanges a native client's Thundera access token for a Swarm API key (used by the desktop app).
- Auth
- Thundera access token
- Body / query
name(optional)- Response
- 201 with the key record and the one-time
key - Errors
- 401
POST /api/v1/api-keys
Creates an API key. The secret is returned once.
- Auth
- Session or API key
- Body / query
name(1-120 chars)- Response
- 201
{id, name, prefix, created_at, key} - Errors
- 401
GET /api/v1/api-keys
Lists your keys (prefix only, never the secret).
- Auth
- Session or API key
- Body / query
- —
- Response
{keys:[...]}- Errors
- 401
DELETE /api/v1/api-keys/:id
Revokes one of your keys.
- Auth
- Session or API key
- Body / query
- —
- Response
{ok:true}- Errors
- 401, 404
POST /api/v1/api-keys/self/revoke
Revokes the key used to make this call.
- Auth
- API key
- Body / query
- —
- Response
{ok:true}- Errors
- 401
Credits and billing
GET /api/v1/credits/balance
Current balance.
- Auth
- Session or API key
- Body / query
- —
- Response
{credit_balance, as_of}- Errors
- 401
GET /api/v1/credits/history
Your ledger, newest first.
- Auth
- Session or API key
- Body / query
- Query:
limit(1-200, default 50),before(ISO time) - Response
{entries:[{id, type, credits, reason, usage_event_id, created_at}], has_more}- Errors
- 400, 401
Account
GET /api/v1/account
Identity, plan, balance, consumed/total credits and 30-day usage by model.
- Auth
- Session or API key
- Body / query
- —
- Response
{user, plan, balance_credits, consumed_credits, total_credits, usage, links}- Errors
- 401
GET /api/v1/usage/events
Your raw usage events, paginated backwards.
- Auth
- Session or API key
- Body / query
- Query:
limit,before - Response
{events:[...], has_more}- Errors
- 401
POST /api/v1/feedback
Sends feedback from the app. Rate limited per user.
- Auth
- Session or API key
- Body / query
kind,message,app_version- Response
- Accepted record
- Errors
- 400, 401, 429
Downloads
GET /api/v1/downloads
Release manifest: version and each artifact with size, SHA-256, signing and notarization.
- Auth
- None
- Body / query
- —
- Response
{product, version, generated_at, artifacts[]}- Errors
- 429, 503
GET /api/v1/downloads/:filename
Streams one allow-listed artifact.
- Auth
- None
- Body / query
- —
- Response
- File bytes
- Errors
- 404, 429
Health
GET /health
Liveness.
- Auth
- None
- Body / query
- —
- Response
{status:'ok'}- Errors
- —
GET /ready
Readiness (database reachable).
- Auth
- None
- Body / query
- —
- Response
{status}- Errors
- 503