Grant and review access to a Library

A resource grant names one Library. An agent can read it when a resource grant or tenant-wide access policy allows the action. A refusal written on a Library is a grant whose effect is deny. It holds against every allow, including the one a tenant administrator carries.

Behavior on this page was checked against the shipped platform on 2026-08-30. It is current behavior, not a commitment.

You decide those grants outside the task. During a task an agent lists documents, searches for meaning, matches a literal string, and reads lines back. None of those tools writes a grant.

Agents and access owns the agent, its two credentials, and its lifecycle. Design your Libraries owns how many Libraries to create and which agent reaches each.

What each action allows

library:upload covers the tenant. The other four actions apply to the Library the request names, so a subject can hold one of them on one Library without holding it anywhere else.

That split is what you plan around. Give a team library:write on the two Libraries it owns, and that resource grant permits writes to those two only. Check that no tenant-wide role or policy permits wider access. SDK reference lists the client operation that each action guards.

The shape of a grant

A grant carries three fields and nothing else.

A trailing * matches every subject, or every action, that starts with the text before it. Give each team’s agents a common prefix and one grant covers the team: agent:payments-* reaches every agent whose identifier starts with payments-. A wide prefix is as wide as it looks. Read it as the set of identifiers it admits today, and the ones someone can create tomorrow.

A refusal beats every allow

Write a refusal when one subject must stay out of a Library that a wider allow already reaches. The platform reads the refusals on a Library first, so the refusal decides, whatever else grants the action.

The order in which the platform answers one Library requestThe platform answers a request for one action on one Library in four steps. A refusal on that Library refuses the request. If there is no refusal, a built-in role or a tenant-wide access policy can allow the action. If neither covers it, an allow grant on that Library allows it. If nothing matches, the platform refuses.

A refusal survives a later allow. Adding an allow beside it changes nothing, and access returns only when someone revokes the refusal itself. That makes a refusal the right tool for a named exception and the wrong tool for a default. Grant narrowly first, and refuse only what a narrow grant cannot express.

Name a subject in every refusal. A refusal whose subject is * is rejected as you write it, because it would refuse every administrator as well and leave no route to undo it.

Who can grant what

Creating a Library grants the creating agent every action on it, library:admin included. That agent then grants, refuses, and revokes on the Library it created. The creator grant gives that power on the Library it created; it grants nothing on another Library. Library creation is therefore an access-control capability, not a storage one.

Every agent holds library:upload across the tenant by default, so every agent can create a Library and administer the one it created. Give each team its own agent, so the Libraries one team creates stay under one identifier that you can name in a grant.

library:admin on a Library grants only the ability to read and change its grants. It does not imply library:read, library:write, or library:delete. A subject that holds library:* has all five actions.

Only a tenant administrator grants library:upload. The platform checks it against the tenant, so no per-Library grant carries it.

library:write is normally the action a caller must be granted. A caller that has to add documents to a Library someone else created already holds library:upload. The action it lacks is library:write on that Library.

Where a grant is not the boundary

A grant decides which subject reaches which Library. Three questions it does not answer, and what answers each.

A separate tenant is the boundary against a person

The built-in viewer role reads every Library in the tenant. The built-in editor role reads, writes, and uploads to every one of them. An allow grant only adds to what those two roles already reach. A refusal does hold against a role, but you write one for each Library and each named subject, and both roles reach every Library you create later. When a person must not reach a body of documents at all, put those documents in a separate tenant and give that person no role in it.

The agent is the boundary for one task

An agent’s document tools reach every Library that agent can read, on every task, and not only the files that task attached. A grant is not a task-level scope. Give each job its own agent, and grant that agent the Libraries that job needs. Attach documents covers the files that one task carries.

A narrow grant also reduces incomplete answers. How an agent finds an answer explains why and states what to do when an answer reports that it stopped.

The Library is the boundary for a document

A grant applies to a whole Library, and there are no per-document grants. The Library is the unit you draw the line around. Put one audience’s documents in one Library, and grant that Library. Design your Libraries covers how to split a corpus you already hold.

Review Library-specific grants

Reading a Library’s grants needs library:admin on it, and so does adding or revoking one. The Dashboard carries that control: it lists the grants on a Library, and adds or revokes one. The core Python client has no grant method. SDK reference lists every Dashboard-only Library capability.

Read that list as the Library-specific grants you decided, not as a complete list of subjects that can reach the Library. Built-in roles and tenant-wide access policies can also allow access; a Library refusal still wins over them. Allow up to one minute for a permission change to take effect, then verify it by the call it must now refuse or allow. Agents and access separates this delay from the shorter token-revocation window.

The platform records authorization decisions when it computes them, and each grant you add or revoke. It does not record a document read. Security and data handling states what those records hold and how long they live.