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

# Authentication

> Workspace API keys for machines, sessions for people. Never both on one request.

## API keys

Send the key as a bearer token. A key is bound to one workspace and carries scopes.

```bash theme={null}
curl https://api.refmatter.com/v1/references \
  -H "Authorization: Bearer $REFMATTER_API_KEY"
```

| Scope              | Allows                                   |
| ------------------ | ---------------------------------------- |
| `ingestions:write` | Create and cancel ingestions             |
| `ingestions:read`  | Read ingestion state                     |
| `references:read`  | List and read references                 |
| `references:write` | Annotate, delete, and manage media holds |
| `media:read`       | Create short-lived download URLs         |

Keys are shown once at creation and stored as a digest. Revoke a key with `DELETE /v1/workspaces/{workspaceId}/api-keys/{keyId}`; revocation is immediate.

## Sessions (people)

Workspace owners sign in with `POST /v1/auth/sessions` and receive an `HttpOnly` cookie. State-changing session requests must carry an `Origin` header equal to the web origin. Sessions are how owners create API keys:

```bash theme={null}
curl -X POST https://api.refmatter.com/v1/workspaces/$WORKSPACE_ID/api-keys \
  -b cookies.txt -H "Origin: https://refmatter.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent","scopes":["ingestions:read","ingestions:write","references:read","references:write","media:read"]}'
```

<Warning>
  A request that carries both a session cookie and a bearer token is rejected with
  `credential_conflict`.
</Warning>

## Request ids

Send `X-Request-Id` to correlate a call with your own logs; it is echoed back on every response and included in error envelopes.