> ## 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.

# Access Policy

> Control who can query, read, and manage a document.

## 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

```json theme={null}
{
  "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

<RequestExample>
  ```bash theme={null}
  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"]
          }
        ]
      }
    }'
  ```
</RequestExample>

### Response (200)

```json theme={null}
{
  "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:

```json theme={null}
{
  "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)

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

### Org-internal document

```json theme={null}
{
  "grants": [
    { "principal": { "type": "owner" }, "actions": ["admin"] },
    { "principal": { "type": "org", "id": "org_xyz" }, "actions": ["query", "read_content"] }
  ]
}
```

### Time-limited share

```json theme={null}
{
  "grants": [
    { "principal": { "type": "owner" }, "actions": ["admin"] },
    {
      "principal": { "type": "user", "id": "user_abc" },
      "actions": ["query", "read_content"],
      "constraints": { "expires_at": "2026-04-01T00:00:00Z" }
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.