> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate sovseal API Requests with Bearer Tokens

> Learn how to authenticate every sovseal API request using project tokens, live API keys, or session JWTs — and which token type fits each use case.

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:

```http theme={null}
Authorization: Bearer <TOKEN>
```

Replace `<TOKEN>` with one of the three token types described below.

## Token Taxonomy

| Token Type    | Prefix         | Tier             | Server Lookup           |
| ------------- | -------------- | ---------------- | ----------------------- |
| Project Token | `sov_proj_`    | Free / Stateless | None                    |
| Live API Key  | `sov_live_`    | Paid / Hashed    | SHA-256 hash lookup     |
| Session JWT   | *(WorkOS JWT)* | Dashboard        | `workos_user_id` lookup |

### 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](/platform/features/limits-and-slas).

<Note>
  `agent_id` is a field **you supply** on every `AgentStateClient.snapshot()` call (see [POST /snapshot](/api-reference/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.
</Note>

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](/api-reference/api-keys) 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).

<Warning>
  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.
</Warning>

## Common Authentication Errors

| Error Code                        | HTTP Status | Cause                                                          |
| --------------------------------- | ----------- | -------------------------------------------------------------- |
| `missing_or_invalid_bearer_token` | 401         | The `Authorization` header is absent or malformed.             |
| `session_jwt_required`            | 401         | A dashboard route received an agent API key.                   |
| `invalid_session`                 | 401         | Your WorkOS session JWT is expired or invalid.                 |
| `invalid_api_key`                 | 401         | The `sov_live_` key hash was not found in the database.        |
| `api_key_revoked`                 | 401         | The key was revoked and is no longer valid for any operation.  |
| `owner_not_found`                 | 401         | The key owner's account record does not exist on the platform. |