Library access: policies, Grants, and path-based rules

Two boundaries decide who can reach a Library. Choose each one separately:

• A Tenant access policy adds access through a direct person or Agent Identity binding, or through group membership. Its resource pattern can name one Library path or every path under a prefix.
• A Library Grant allows or refuses one concrete person or Agent Identity on one Library path.

Both can affect one Library operation. A refusal written on a Library is a Grant whose effect is deny; it holds against every allow, including one from a supplied policy.

You decide those Grants outside the Task. During a Task, the model uses the Library Tools on the Libraries that the Task’s Agent Identity can reach, to list documents, search for meaning, match a literal string, and read lines back. None of those Tools writes a Grant.

Credentials and lifecycle defines Agent Identity credentials and lifecycle. Design your Libraries explains how many Libraries to create and which Agent Identity reaches each.

Access follows the Library path

Duale AI decides each Library operation on the Library’s current path, as the resource library:<path>. For example, the Task attachment Library at agent/payments-invoice-review/task/task-000001 is the resource library:agent/payments-invoice-review/task/task-000001. The Library ID still identifies the Library in API calls, but Tenant access policies and Library Grants name its path.

• Libraries at the same path share its access. Every policy and Grant that covers the path applies to each Library there.
• A rename moves the Library to the new path’s access. Renaming requires library:write on both the current and the new path. Grants on the old path stay on that path; they do not follow the Library.
• Deleting a Library leaves the Grants on its path. They apply to any later Library at that path, whether created or renamed there. Before you delete a Library, revoke each Grant that must not carry over, because a deleted Library accepts no Grant change.
• A path cannot contain {, } or *. In a resource pattern, braces mark placeholders and * is a wildcard.

Choose paths with access in mind. When one audience’s Libraries share a prefix, one Tenant access policy on a pattern such as library:finance/* covers all of them, including Libraries created there later.

What each action allows

library:upload applies to the Tenant: Duale AI checks it on tenant:<tenant_id>, and the supplied policies grant it on tenant:*. The other four actions apply to a Library path, so a subject can hold one of them on one path without holding it anywhere else.

Adding a document needs both: library:upload to start the upload, and library:write on the destination Library’s path to add the document to it.

That split is what you plan around. Give a team one library:write Grant on each of the two Libraries it owns. Those Grants permit writes to the Libraries at those two paths only. Check that no supplied tier or other Tenant policy permits wider access. SDK reference lists the client operation that each action guards.

The shape of a Library Grant

To add a Grant from the selected Library, you supply three fields. Duale AI writes the Grant on that Library’s current path.

The Dashboard selector creates a Grant for one concrete person or Agent Identity. It does not expand a group’s members or create a wildcard subject. Use a Tenant access policy when permission must follow a group.

A refusal beats every allow

Write a refusal when one subject must stay out of a Library that a wider allow already reaches. A refusal on the Library’s path decides, whatever else grants the action.

The order in which Duale AI answers one Library requestDuale AI answers a request for one action on one Library in four steps, using the Library's current path. A refusal on that path refuses the request. If there is no refusal, a supplied or Tenant-authored policy can allow the action. If neither covers it, an allow grant on that path allows it. If nothing matches, Duale AI 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.

Who can grant what

Creating a Library requires library:write on the requested path. If an active Library already uses that path, Duale AI returns it instead of creating another. Creation adds no Grant: the policies and Grants that already cover the path decide who reaches the new Library. When creation stops before it finishes, any caller with library:write on that path can repeat the request to complete it.

Every Agent Identity receives, through the supplied Agent default, library:upload on the Tenant and library:read and library:write on library:agent/{self}/*. Duale AI replaces {self} with the calling Agent Identity’s ID, so each Agent Identity can create, fill, and read Libraries under its own agent/<agent_id>/ path, including the Task attachment Libraries the SDK creates for it. Reaching another Agent Identity’s folder, deleting a Library, or managing Grants needs another policy or Grant. Default policies lists the supplied Library access. Use a separate Agent Identity when Libraries need a different credential, authorization, Tool ownership, Task attribution, or review boundary.

library:admin on a path 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 action = library:* on that path has those four Library-scoped actions, not Tenant-scoped library:upload.

To write an allow Grant, the actor also has to be able to pass on the requested action on that path. Duale AI refuses the write if the actor cannot; library:admin alone does not grant it. A deny Grant passes on no access, so it needs library:admin but not the denied action. A refusal on one path also stops that actor from passing on a broader permission that would include that path.

Granting library:upload through a Tenant access policy requires policy-authoring authority and conferral. The author needs profile:manage_policy on policy:<name> and must be able to pass on (library:upload, tenant:*). Tenant access policies owns the common authoring rule. No Library Grant carries Tenant-scoped library:upload.

library:write is normally the action a caller must be granted. Outside its own agent/<agent_id>/ folder, an Agent Identity needs library:write on the path to create a Library or add documents. For a path that no Library uses yet, grant it through a Tenant access policy, because you add a Library Grant from a Library that already exists.

Where a Library Grant is not the boundary

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

A separate Tenant is the boundary against a person

The supplied Viewer tier reads every Library in the Tenant. The supplied Editor tier reads, writes, and uploads to every one of them. An allow Grant only adds to what those two tiers already reach. A refusal does hold against a tier, but you write one for each path and each named subject, and both tiers 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 without that person’s membership.

The Agent Identity is the authorization boundary across Tasks

The Library Tools of a Task can reach every Library allowed to the Task’s Agent Identity, across Tasks, and not only the files attached to the current Task. By default, that includes every Library under the Agent Identity’s own agent/<agent_id>/ folder, such as the attachment Libraries of its earlier Tasks. A Grant is not a Task-level scope. When two jobs need different Library reach or attribution, use separate Agent Identities and grant each only the Libraries it needs. Attach documents covers the files that one Task carries.

A Task’s Library Tools act with the Library access of the Agent Identity the Task belongs to, and the API token that the SDK uses decides that Agent Identity. Anyone who holds an Agent Identity’s API token therefore runs Tasks with that identity’s Library reach, and those Tasks can use Recall to read the requests and final answers of its earlier Tasks. Protect each token as that boundary. Context continuity explains the Recall reach.

The Library is the boundary for a document

A Library Grant applies to every Library at its path, 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 at its own path, and grant that Library. Design your Libraries covers how to split a corpus you already hold.

A Grant change applies to images already in use

Each time a Task sends its history to a model, including in a continuation Task, Duale AI checks each image in that history again: the Agent Identity the Task belongs to must still hold read access to the Library, and the document must still exist with that image. When a Grant change removes that access, or the document or Library is deleted, the model receives a short note in place of the image. The text in the history stays, including text derived from the image. The image replacement rules also apply each time. A permission change takes effect within the propagation time stated in Review Library-specific Grants. Neither a Grant change nor a deletion recalls data already sent to a provider.

Review Library-specific Grants

Reading a Library’s Grants needs library:admin on its path, and so does adding or revoking one. The Dashboard carries that control: it lists the Grants on a Library’s current path, and adds or revokes one. Those Grants also apply to any other Library at the same path. 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. Supplied and Tenant-authored 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 repeat the affected operation and confirm the intended allow or refusal. Credentials and lifecycle explains the separate API-token revocation window: revocation blocks renewal, but an issued platform token can remain usable for the rest of its eight-hour lifetime.

Duale AI records some authorization decisions and every Grant change. It does not record which document was read. Security and data handling states what those records show and what they do not.