Access rules

Create an enforced collection

Use a cluster key or a namespace key with write. The example uses a separate collection named people-docs, so the quickstart collection can keep access control off.

POST /namespaces/acme/collections HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json
Idempotency-Key: acme-people-docs-collection

{
  "name": "people-docs",
  "access_control": "enforced"
}

The response is a collection with access_control: "enforced". Its initial root rule has readers: []. No content is retrievable until you grant readers access.

Grant access to a prefix

Grant HR readers access to /hr/. A folder target must end with /. Send exactly one of folder or file.

POST /namespaces/acme/collections/people-docs/access-rules HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "folder": "/hr/",
  "readers": [
    "group:hr",
    "user:u_8812"
  ],
  "sealed": false
}

{
  "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"
}

If existing files must move under this rule, the response is 202 with { "rule": ..., "job": ... }. That notation describes the response fields, not literal JSON. Wait for the job’s success event. Affected files remain hidden from retrieval until it completes.

A rule can precede its files. Add /hr/handbook.pdf using Add file, then wait for processing. To grant collection-wide access, create or update the root folder target /.

Send trusted principals

Your application authenticates the person and resolves every relevant group. Send those exact strings to Engine. Engine does not expand groups or authenticate the supplied names.

POST /namespaces/acme/collections/people-docs:search HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "query": "annual leave",
  "principals": [
    "user:u_8812",
    "group:hr"
  ],
  "mode": "hybrid"
}

Use the same principals field on Answer and Research. Missing principals on an enforced collection return 400 invalid_request. An empty list allows no content. Sending principals to a collection with access control off also returns 400 invalid_request.

Understand inheritance and sealing

The highest sealed ancestor governs when more than one sealed folder covers a file. Otherwise, the closest rule governs. A file rule cannot be sealed. Paths are case-sensitive: /HR/ and /hr/ are different targets.

Change readers and rules

To change some readers without replacing the whole list, use add_readers and remove_readers. A principal cannot appear in both lists. Do not combine either list with readers.

PATCH /namespaces/acme/collections/people-docs/access-rules/acr_01J8Z3K4N5P6Q7R8S9T0V1W2X3 HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "add_readers": [
    "user:u_9001"
  ],
  "remove_readers": [
    "user:u_8812"
  ]
}

Reader-only changes return 200 and apply on the next request. Creating, deleting, or sealing rules can change which rule governs files. Those changes can return an apply_access_rule job. The root rule cannot be deleted.

Use Batch access rules when several changes must succeed together. The batch requires an idempotency key. An invalid operation fails the whole batch. A conflicting running rule job returns 409 operation_in_progress.

Keep writes and filters separate

Access rules control retrieval. They do not authorize human file changes. Your application checks a person’s write permissions before it uses an API key with write.

Metadata filters select relevant data. They do not secure it, because the API caller can omit them. Engine applies access rules before a file contributes a span or answer content.

See Create access rule, Update access rule, and Principals and access rules for the detailed contract.