curl -X PUT https://api.okrapdf.com/v1/documents/doc-abc123/config \
-H "Authorization: Bearer okra_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"access": {
"default_effect": "deny",
"grants": [
{
"principal": { "type": "owner" },
"actions": ["admin"]
},
{
"principal": { "type": "public" },
"actions": ["query", "read_content", "read_meta"]
}
]
}
}'
Documents
Access Policy
Control who can query, read, and manage a document.
PUT
/
v1
/
documents
/
{id}
/
config
curl -X PUT https://api.okrapdf.com/v1/documents/doc-abc123/config \
-H "Authorization: Bearer okra_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"access": {
"default_effect": "deny",
"grants": [
{
"principal": { "type": "owner" },
"actions": ["admin"]
},
{
"principal": { "type": "public" },
"actions": ["query", "read_content", "read_meta"]
}
]
}
}'
Overview
Every document has an access policy that controls who can interact with it. The policy uses a deny-by-default model with explicit grants.Policy shape
{
"access": {
"default_effect": "deny",
"grants": [
{
"principal": { "type": "owner" },
"actions": ["admin"]
},
{
"principal": { "type": "public" },
"actions": ["query", "read_content", "read_meta"]
}
]
}
}
Principals
| Type | Matches | Use case |
|---|---|---|
owner | The user who uploaded the document | Full control |
public | Any caller, no auth required | Public-facing documents (HKEX filings, shared reports) |
user | A specific user ID | Shared with a teammate |
org | All members of an org | Org-wide access |
project | All keys scoped to a project | Project-level access |
Actions
| Action | What it permits |
|---|---|
admin | All operations (superset) |
query | Chat completions, structured extraction |
read_content | Page markdown, node content |
read_meta | Document status, metadata |
download_pdf | Original PDF download |
update_config | Change settings and access policy |
trigger_extract | Start extraction jobs |
publish | Publish to public corpus |
create_link | Create share links |
list_links | View existing share links |
Setting the policy
curl -X PUT https://api.okrapdf.com/v1/documents/doc-abc123/config \
-H "Authorization: Bearer okra_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"access": {
"default_effect": "deny",
"grants": [
{
"principal": { "type": "owner" },
"actions": ["admin"]
},
{
"principal": { "type": "public" },
"actions": ["query", "read_content", "read_meta"]
}
]
}
}'
Response (200)
{
"document_id": "doc-abc123",
"config_version": 1,
"config": {
"access": {
"default_effect": "deny",
"grants": [
{ "principal": { "type": "owner" }, "actions": ["admin"] },
{ "principal": { "type": "public" }, "actions": ["query", "read_content", "read_meta"] }
]
}
}
}
Grant constraints
Grants can have optional constraints:{
"principal": { "type": "user", "id": "user_abc" },
"actions": ["query"],
"constraints": {
"expires_at": "2026-06-01T00:00:00Z",
"not_before": "2026-03-01T00:00:00Z"
}
}
| Constraint | Effect |
|---|---|
expires_at | Grant stops working after this time |
not_before | Grant only active after this time |
redaction_role | Applies PII redaction profile (admin, viewer, public) |
Common patterns
Public document (anyone can chat)
{
"grants": [
{ "principal": { "type": "owner" }, "actions": ["admin"] },
{ "principal": { "type": "public" }, "actions": ["query", "read_content", "read_meta"] }
]
}
Org-internal document
{
"grants": [
{ "principal": { "type": "owner" }, "actions": ["admin"] },
{ "principal": { "type": "org", "id": "org_xyz" }, "actions": ["query", "read_content"] }
]
}
Time-limited share
{
"grants": [
{ "principal": { "type": "owner" }, "actions": ["admin"] },
{
"principal": { "type": "user", "id": "user_abc" },
"actions": ["query", "read_content"],
"constraints": { "expires_at": "2026-04-01T00:00:00Z" }
}
]
}
⌘I