Docs Scopes

Table scopes decide which rows a key can reach. Docs scopes decide which documents it can reach. They are separate lists, and neither one implies the other.

You set them on the Docs tab of an API key or an AI connector.

Why documents need their own axis

A workspace's documents are not rows. They live in a tree of folders and spaces, they are edited by people rather than written by integrations, and what belongs in one is usually prose rather than fields — meeting notes, contracts, specs, a client's file.

That difference matters for permissions. Table scopes are per table, and a table is a flat thing you either allow or do not. Documents are a hierarchy, and the useful grant is almost always "this branch, except that one page in it".

So the Docs axis is a tree of grants rather than a list.

What you can grant on

A grant targets one of four things:

A grant on a folder covers everything beneath it, recursively. You do not restate it for each child.

The levels

Inheritance, and the one distinction that matters

This is the part worth being precise about, because two situations look the same in the UI and behave completely differently.

A target with no grant of its own inherits from its nearest ancestor that has one. Nothing is stated about it, so the tree answers for it.

A target explicitly set to `None` does not inherit. It is blocked, even if its parent folder is granted Full.

  Root                     (no grant)
   └── Clients             Read          <- everything below is readable...
        ├── Acme                         <- inherits Read
        ├── Beta                         <- inherits Read
        └── Internal       None          <- ...except this branch

That is how you say "the whole client folder, except the internal notes" — one grant plus one exclusion, instead of listing every folder you do want.

The nearest ancestor wins, so a None deep in a granted tree carves out exactly that subtree, and a grant inside a None subtree opens exactly that one branch back up.

A key with no grants at all reaches no documents. The default is nothing, not everything — a new key cannot read a document until somebody says which.

What this means in practice

Grant the branch, not the pages. A grant on a folder keeps working when somebody adds a document to it. A list of individual documents silently stops covering new material, and nobody notices until an integration is missing something it should have had.

Use `None` for the exception, not the rule. If you find yourself writing more exclusions than grants, the grant is at the wrong level — move it down the tree.

Reads and writes are the same axis here. Unlike table scopes, there is no separate read list and write list: the level on the grant says which. Read on a folder means an integration can summarise everything in it and change none of it, which is the right setting for most AI connectors.

Think about `Full` before you use it. It includes delete, and a document is not a row — losing one loses prose somebody wrote. ReadWrite covers every integration that edits documents; reserve Full for something whose actual job is cleaning up.

Docs scopes and MCP tools

The two are checked separately, and both have to pass.

Enabling the Docs tool group lets a key call the document tools at all. It does not grant a single document — the Docs scopes still decide which ones those tools can see. A connector with the Docs tool group and no Docs scopes can call the tools and will find nothing.

The reverse is also true: Docs scopes on a key whose Docs tool group is off do nothing over MCP, because the call is refused before scopes are consulted.

When a document read fails unexpectedly, check both — the error tells you which axis stopped it.

Next

• Credentials and Principals — the three axes and how they compose.

• MCP Tool Permissions — the group and override model.