Skip to main content

​
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:
MethodHeaderUse case
API keyAuthorization: Bearer okra_sk_...Server-to-server
Publishable keyAuthorization: Bearer okra_pk_...Browser clients
Shared secretx-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). 
{
  "access": {
    "default_effect": "deny",
    "grants": [
      { "principal": { "type": "owner" }, "actions": ["admin"] },
      { "principal": { "type": "public" }, "actions": ["query", "read_content"] }
    ]
  }
}
See Access Policy for the full reference.

​
Route classes

​
Public read surface (/v1/documents/...)

Published outputs, CDN-cacheable. Access controlled by document grants.
  • GET /v1/documents/{id} — metadata
  • GET /v1/documents/{id}/pages/{n} — page content
  • POST /v1/public/resolve/chat/completions — public source chat

​
Private authenticated surface (/document/...)

Mutations and configuration. Requires API key or shared secret.
  • PUT /document/{id}/config — set access policy
  • POST /document/{id}/reparse — re-process
  • POST /document/{id}/extract — trigger extraction

​
Caching

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