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

# Authentication

> Use API keys for REST requests and short-lived tokens for realtime subscriptions.

CapOut uses two auth models:

| Use case                                                                                         | Auth method                                          |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| REST endpoints like `/upload`, `/status/{document_id}`, `/documents`, `/claims`, and `/ws/token` | `capout-api-key` request header                      |
| Realtime subscriptions over `/ws/status` and `/sse/status`                                       | `token` query parameter returned by `POST /ws/token` |

## API key header

Send your organization-scoped API key in the `capout-api-key` header on REST calls.

```bash theme={null}
curl https://api.capout.ai/documents \
  -H "capout-api-key: $CAPOUT_API_KEY"
```

## Realtime tokens

Realtime connections do not use the API key directly. Instead:

1. Call `POST /ws/token` with your API key.
2. Read `token`, `ws_url`, `sse_url`, and `expires_at`.
3. Connect with `?token=<token>` in the query string.

This separation matters for browser clients, especially for SSE, where setting custom headers is not supported by `EventSource`.

## Token-based stream URLs

Specific documents:

```text theme={null}
wss://api.capout.ai/ws/status?token=<token>&document_id=doc_123
https://api.capout.ai/sse/status?token=<token>&document_id=doc_123
```

Recent organization documents:

```text theme={null}
wss://api.capout.ai/ws/status?token=<token>&recent=10
https://api.capout.ai/sse/status?token=<token>&recent=10
```

## Expiration strategy

Treat realtime tokens as short-lived connection credentials:

* Mint them just before opening a stream.
* Re-mint on reconnect if the token has expired.
* Keep API keys on trusted backend infrastructure when possible.