API Authentication

Thallus supports two authentication methods: JWT sessions for web browser interactions and API keys for programmatic access. Both methods identify your user account and carry the same permissions — the difference is how you obtain and present credentials.

JWT authentication

The web interface uses JSON Web Tokens (JWT) for session management. When you log in, the server returns an access token and sets a refresh token cookie.

Obtaining a token

Send your credentials to the login endpoint:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

A successful response includes:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": "...", "email": "user@example.com", "name": "..." },
  "expires_in": 900
}

The expires_in value is in seconds. The response also sets a refresh token as an HttpOnly cookie for automatic token renewal.

Using the token

Include the access token in the Authorization header on every request:

Token expiry and auto-refresh

Access tokens are short-lived and auto-refreshed. The web interface automatically refreshes tokens before expiry using the refresh token cookie. If you're building a custom client, call the refresh endpoint before the token expires:

POST /api/v1/auth/refresh
Cookie: <refresh_token_cookie>

This returns a new access token and rotates the refresh cookie.

Inactivity timeout: If a session inactivity timeout is in effect (configured at the platform, org, or user level), the refresh endpoint returns 401 with an inactivity message when the user has been idle beyond the allowed duration. Clients should redirect to the login page when this occurs. See Inactivity timeout for details.

Refresh token rotation

Refresh tokens use rotation with compromise detection. When you refresh, the old token is revoked and a new one is issued.

Key details:

• Refresh tokens are stored as HttpOnly, Secure cookies with a strict SameSite policy
• Cookies are rotated on each use
• JavaScript cannot read the cookie — it's automatically sent by the browser

Reuse detection: Thallus detects and prevents refresh token reuse. If a compromised token is detected, all related sessions are revoked for security.

API key authentication

API keys are long-lived credentials for scripts, CI/CD pipelines, and integrations. They follow the format thal_<random>.

Using an API key

Include the key in the X-API-Key header:

API keys grant the same permissions as your user account. All actions are attributed to your user in audit logs.

Key security

• Keys are securely hashed at rest — Thallus never stores raw keys
• The raw key is displayed exactly once at creation time
• After creation, only a masked preview is visible (prefix + suffix)
• Each key tracks its last-used timestamp for monitoring
• Revoked keys stop working immediately and cannot be un-revoked

Creating and managing keys

Create and manage API keys in Settings → API Keys, or via the API:

See API Keys for the full setup guide.

Authentication priority

When both a JWT and an API key are present in the same request, the JWT takes precedence. The server evaluates credentials in this order:

1. Authorization: Bearer <token> header (JWT)
2. X-API-Key header (API key)

If neither is present, the request is rejected with a 401 response.

Authorization levels

Thallus uses three authorization levels. Each level includes the permissions of the levels below it.

Endpoint documentation in Core API Endpoints indicates the required authorization level for each route.

Related pages

• API Keys — creating and managing API keys in the dashboard
• Password & Security — session security and password policies
• Rate Limiting — request limits for authenticated and unauthenticated endpoints
• Error Handling — authentication error responses (401, 403)