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

# Security Model

> How authentication and access control work across the API.

## Two layers

1. **Authentication** — who is calling (API key, shared secret, JWT)
2. **Access policy** — what the caller can do on a specific document

## Authentication

Every request is authenticated via one of:

| Method          | Header                              | Use case                  |
| --------------- | ----------------------------------- | ------------------------- |
| API key         | `Authorization: Bearer okra_sk_...` | Server-to-server          |
| Publishable key | `Authorization: Bearer okra_pk_...` | Browser clients           |
| Shared secret   | `x-document-agent-secret: ...`      | Internal worker-to-worker |

Unauthenticated requests can still interact with documents that have a `public` grant in their access policy.

## Access policy

Each document has a deny-by-default access policy with explicit grants. A grant maps a **principal** (who) to **actions** (what).

```json theme={null}
{
  "access": {
    "default_effect": "deny",
    "grants": [
      { "principal": { "type": "owner" }, "actions": ["admin"] },
      { "principal": { "type": "public" }, "actions": ["query", "read_content"] }
    ]
  }
}
```

See [Access Policy](/api-reference/documents/access-policy) for the full reference.

## Route classes

### Document and source read surface (`/v1/documents/...`)

Processed outputs and public-source chat. Access is controlled by API credentials, source resolution, and document grants where applicable.

* `GET /v1/documents/{id}` — metadata
* `GET /v1/documents/{id}/pages/{page}` — page content
* `POST /v1/public/resolve/chat/completions` — public source chat

### Authenticated mutation surface (`/v1/...`)

Mutations and configuration require an API key.

* `POST /v1/documents` — upload and process a document
* `PUT /v1/documents/{id}/config` — set document config and access policy
* `POST /v1/files` — upload a passive file asset
* `POST /v1/host` — publish a hosted PDF deployment

## Caching

* Public routes: `Cache-Control: public` (CDN-safe)
* Private routes: `Cache-Control: private` or `no-store`