Principals and access rules
AI DraftControl which files can contribute to a reader’s results and answers.
Access rules limit which files can contribute to a reader’s Search results and Query answers. Your application supplies the reader’s user and group names as principals.
Application access and reader access
Trusted application
user:u_8812 · group:hr
Authenticate the reader and resolve their groups.
Enforced collection
people-docs
The API key allows access to this collection.
Governing rule
/hr/ → readers: group:hr
At least one supplied principal must match a reader.
Allowed
/hr/handbook.pdf
Its content can enter results and answers.
No matching grant
/finance/budget.pdf
Its content stays outside this reader’s retrieval.
The closest rule governs unless a sealed ancestor controls the entire subtree.
Your application authenticates people and resolves their groups. Engine compares principal strings exactly. For example, user:u_8812 and group:hr have meaning because your application assigned it. Engine does not authenticate those names or expand group membership.
Send the complete principal list from a trusted backend. An API key holder controls this list, so an end user must not choose arbitrary principals.
Targets and readers
Rule for the HR prefix
{
"id": "acr_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
"folder": "/hr/",
"readers": [
"group:hr",
"user:u_8812"
],
"sealed": false,
"created_at": "2026-10-06T12:00:00Z",
"updated_at": "2026-10-06T12:00:00Z"
}A rule selects exactly one folder prefix or one file path. A folder ends with /; / covers the collection. /hr/ covers /hr/handbook.pdf but not /hrm/report.pdf. A rule may exist before any matching files.
readers is the allowed principal list. A reader needs at least one exact match with its own principals. An empty reader list grants no access.
Choose the governing rule
Normally, the closest rule governs a file. A file rule is closer than any folder rule. A deeper rule replaces its parent’s readers; it does not add to them. To preserve parent access, include those readers in the deeper rule.
A folder rule with sealed: true governs all content below it. If several sealed folders cover a file, the highest sealed folder governs. Rules below that boundary cannot broaden or narrow access. File rules cannot be sealed.
Enforced and off
A collection defaults to access_control: "off". It rejects Search or Query requests containing principals. An enforced collection requires principals; an empty list allows no content. Every key, including a cluster key, follows these rules.
An enforced collection starts with a root rule whose readers are empty. Grant access before retrieval. Reader changes apply on the next request. Changes to which rule governs files can return a job and temporarily hide affected content.
Access rules restrict retrieval, not writes. Your application must authorize human file changes before using its write key. A metadata filter is not an access rule. See Apply access rules.