Skip to main content
Every request to the sovseal API must include a bearer token in the Authorization header. The API supports three distinct token types, each serving a different layer of the system: local development, production agents, and dashboard account management. Understanding which token to use prevents authentication errors and ensures you operate within the right access tier.

​
Authorization Header Format

Include the following header on every request:
Replace <TOKEN> with one of the three token types described below.

​
Token Taxonomy

​
Project Tokens (sov_proj_)

Project tokens let you spin up a local agent vector store immediately with no sign-up required. They are self-asserting and completely stateless — the server performs no database lookup when it receives one. Instead, the project ID embedded in the token itself acts as the namespace.
  • Format: sov_proj_[uuid_v4]
  • Pricing: Free tier. There is no rate limiting enforced at the edge function today — see Limits & SLAs.
agent_id is a field you supply on every AgentStateClient.snapshot() call (see POST /snapshot) — the SDK does not compute it for you automatically. A common convention is sha256(project_id + ":" + some_stable_identifier), but this is your choice to make, not a mandated derivation.
Use project tokens for local development, CI pipelines, and any context where zero-friction setup matters more than production billing controls.

​
Live API Keys (sov_live_)

Live API keys are for production agents that need higher throughput, persistent state backups, and custom billing quotas. Unlike project tokens, the server validates these keys on every request.
  • Format: sov_live_[base62_secret]
  • Behavior: The server computes the SHA-256 hash of the submitted key and looks it up in the api_keys table. It then checks the key owner’s active subscription limits.
  • Security: The server never stores your key in plaintext — only its hash is persisted. Save your raw secret immediately after creation; it is shown exactly once.
Issue, list, and revoke live API keys via the API Keys Management endpoints.

​
Session JWTs (Dashboard Auth)

Administrative endpoints — including billing, settings, team management, and API key issuance — require your dashboard session JWT rather than an agent API key.
  • Behavior: The server verifies the JWT against WorkOS AuthKit’s remote JWKS (jose.createRemoteJWKSet + jose.jwtVerify) — there is no locally-configured signing secret. The verified sub claim is matched to public.users.workos_user_id to resolve the canonical account.
  • How to obtain: Your session JWT is issued by WorkOS AuthKit when you sign in to the sovseal dashboard (Magic Auth, Google, or GitHub OAuth).
Sending a sov_live_ or sov_proj_ token to a dashboard-only endpoint returns 401 session_jwt_required. These routes require a user login session, not an agent API key.

​
Common Authentication Errors