Authentication
Documentation for Authentication
Overview
The Supervity platform uses JWT (JSON Web Tokens) issued by a Keycloak identity provider. All user-facing endpoints require a valid JWT token.
Providing the Token
Tokens can be provided in three ways (checked in this order):
1. Cookie (recommended for browser clients)
Cookie: token=<jwt>
2. Query Parameter (useful for SSE streams where headers are limited)
GET /api/v1/chats/:threadId/messages?token=<jwt>
3. Authorization Header (recommended for server-to-server or API clients)
Authorization: Bearer <jwt>
Organization Context (x-active-org)
Most endpoints require an active organization context. Provide it via the x-active-org request header:
x-active-org: your-org-key
If omitted, the server will try to look up the user's previously stored org preference from the database. On first access, the org key is derived from the JWT claims.
Best practice: Always include x-active-org explicitly in every request to avoid ambiguity.
Example Authenticated Request
Token Claims
The JWT payload contains the following relevant fields used by the server:
| Claim | Description |
|---|---|
sub | User ID (UUID) |
email | User email |
realm_access.roles | Realm-level roles |
resource_access | Client-level roles and permissions |
Error Responses
| Status | Meaning |
|---|---|
401 Unauthorized | Token missing, expired, or invalid |
403 Forbidden | Token valid but insufficient permissions |
Rate Limiting
- Limit: 60 requests per minute per IP address
- Backend: Redis-backed sliding window
- Exempt: Private/internal IP addresses
- Header on limit:
Retry-After: <seconds>is included in429responses
CORS
The allowed origin is configured server-side via the CORS_ALLOW_ORIGIN environment variable. Browser clients must be served from that origin.
Team-Based Access Control
Resources (workflows, threads) can be shared with teams. The server applies team-gate filtering automatically based on the JWT's team membership claims. Resources shared with no teams are visible only to the owner.