---
title: Principals and access rules
description: Control which files can contribute to a reader’s results and answers.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Principals and access rules

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

*Illustration: The API key admits the application to a collection. The supplied principals intersect with the governing rule’s readers. Only allowed content enters Search and Query.*

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**

```json
{
  "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](/engine/guides/access-rules).
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.