> ## 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/document/{id}/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" }
    }
  ]
}
```