# Authorization and actors

OmniGraph uses Cedar policy bundles to authorize graph, server, and cluster configuration actions.

Policies are declared in `cluster.yaml` and installed by `cluster apply`. Servers load applied policies at startup and activate policy changes during live deployment, including changes to existing graphs.

## [Actions](/content/docs/operations/policy#actions/index.html)

Graph-scoped actions:

| Action          | Covers                                                   |
|-----------------|---------------------------------------------------------|
| `read`          | Queries, snapshots, branches, and commits               |
| `export`        | Snapshot export                                         |
| `change`        | Mutations, loads, and source metadata probes for `explain load csv` |
| `schema_apply`  | Schema changes                                         |
| `branch_create` | Branch creation                                       |
| `branch_delete` | Branch deletion                                       |
| `branch_merge`  | Branch merge                                          |
| `branch_claim`  | Claim of a branch's [writer epoch](/content/docs/operations/troubleshooting#writer-epoch/index.html) |
| `commit_publish` | Publication of an unpublished commit onto its recorded target branch |
| `commit_drop`   | Drop of an unpublished commit                          |
| `maintain`      | Content-preserving maintenance: optimize, index builds, the full-text rebuild and the repair report |
| `reclaim`       | Cleanup, which permanently removes table versions and files no retained commit needs |
| `invoke_query`  | Entry to a stored query                               |
| `admin`         | Reserved graph administration                           |

`graph_list` is server-scoped and controls the metadata catalog at `GET /graphs`. It does not control the minimal identity-authenticated `GET /graphs/discovery` route: every valid cluster identity can discover all applied graph IDs and display names, without gaining permission to read their schema or contents. See [signed data credentials](/content/docs/operations/server#signed-data-credentials/index.html).

`config_manage` is cluster-scoped. It authorizes configuration changes through the identity-authorized cluster API, including stored queries, graph creation, and policy membership/binding changes on existing graphs. Grants and revocations are authorized by the currently applied policy, never the proposed policy. Changing an existing graph's schema requires that graph's `schema_apply` permission; reading its remote schema or migration preview requires `read` on `main`. The reserved graph `admin` action does not grant cluster management.

A stored mutation requires both `invoke_query` and `change`. A stored read requires `invoke_query` and `read`.

`maintain` and `reclaim` are separate from `change`, so an automation account can compact a graph without the right to write data, and can hold `maintain` without the right to delete history. `maintain` is judged on the branch the operation maintains (`main` for optimize and the repair report) and takes `branch_scope`; `reclaim` covers every branch's history and takes no branch scope. `change` admits no maintenance: index builds and the full-text rebuild need `maintain` on their branch. The engine checks these actions whenever a policy is installed on the graph handle; the direct maintenance commands load no policy (see [maintenance](/content/docs/operations/maintenance/index.html)).

## [Bind a policy](/content/docs/operations/policy#bind-a-policy/index.html)

```yaml
# cluster.yaml
policies:
  graph-access:
    file: graph.policy.yaml
    applies_to: [knowledge]
  server-access:
    file: server.policy.yaml
    applies_to: [cluster]
```

A bundle may target graph IDs or the `cluster` scope, but not both. Only one bundle may bind a given scope. The target `og_catalog` binds the [engine catalogue](/content/docs/queries-search/catalogue/index.html), which every server serves and no `graphs:` entry declares: its `read` rule decides catalogue reads with the resource `og_catalog` and no branch, and the bundle is applied and activated like a graph's.

Example graph policy:

```yaml
version: 1
groups:
  readers: [act-alice, act-bob]
rules:
  - id: readers-can-read
    allow:
      actors: { group: readers }
      actions: [read]
      branch_scope: any
  - id: readers-can-invoke
    allow:
      actors: { group: readers }
      actions: [invoke_query]
```

A cluster-bound bundle can contain separate configuration and inventory rules:

```yaml
version: 1
groups:
  owners: [principal:alice]
rules:
  - id: owners-manage-config
    allow:
      actors: { group: owners }
      actions: [config_manage]
  - id: owners-list-graphs
    allow:
      actors: { group: owners }
      actions: [graph_list]
```

`config_manage` uses the Cedar `Cluster::"root"` resource; `graph_list` uses `Server::"root"`. Put them in separate rules and do not give either a branch scope. Bind this file with `applies_to: [cluster]` as above.

For an identity-authorized apply, the **current applied policy** authorizes all planned effects before any graph or configuration effect. A proposed policy cannot give its author permission to install itself. A saved plan does not transfer its author's permissions: another caller must pass the current policy checks. Explicit first initialization can install a declared initial management policy under an exact bootstrap capability; missing policy on an existing cluster is an error, not permission to bootstrap again. Existing storage-holder cluster APIs keep their explicit trust boundary.

Graph rules may use `branch_scope` for a source branch or `target_branch_scope` for a destination branch. Values are `any`, `protected`, or `unprotected`; a rule may not set both. A branch is protected when the bundle's `protected_branches` list names it exactly:

```yaml
protected_branches: [main, release]
```

Branch names are compared as written. A `protected_branches` entry that is empty, has leading or trailing whitespace, or contains a control character fails policy validation, and a request naming such a branch is refused as a bad request before any rule is evaluated (see [branch names](/content/docs/branching#branch-names/index.html)). Server actions and graph-wide `invoke_query` and `reclaim` rules do not take branch scopes. `commit_publish` and `commit_drop` take `target_branch_scope`: the scope is the branch the unpublished commit recorded as its target. `branch_claim` takes `target_branch_scope` too: the scope is the branch the claim names. Writing an unpublished commit needs no new action: a mutation `as commit` is a `change` on its branch and a merge `as commit` is a `branch_merge`, so an actor with ordinary write rights can omit `as commit`; this is a voluntary review workflow, not an approval boundary (see [Unpublished graph commits](https://github.com/ModernRelay/omnigraph/blob/main/docs/rfcs/2026-10-10-unpublished-graph-commits.md)). A mutation `as unattached branch` is likewise a `change` on the branch it records as its target: the first write's branch, and for a write `on "<id>"` the target the base snapshot recorded, whatever branch the request names. `commit list --unattached` and a query `--snapshot <id>` of an unattached snapshot need `read` on that recorded target; `commit show <id>` keeps its scope-free `read`; `commit drop` takes `commit_drop` on the recorded target as for an unpublished commit (see [Unattached graph branches](https://github.com/ModernRelay/omnigraph/blob/main/docs/rfcs/2026-10-11-unattached-graph-branches.md)). `branch_create` from a branch checks that branch as the source and the new branch as the target. A start at a commit (`from_commit`) checks the branch that wrote the commit as the source; a denial answers `404`, as an id no commit has does, so the id discloses nothing (see [start a branch at a commit](/content/docs/branching#start-a-branch-at-a-commit/index.html)).

## [Validate and test](/content/docs/operations/policy#validate-and-test/index.html)

Policy commands read the applied bundles from a cluster and ask the bundle a server asks: graph actions go to the bundle bound to `--graph`, and `graph_list` and `config_manage` go to the bundle bound to `cluster`. `validate` checks each of the two that is applied, as its own kind; `test` runs each case against the bundle for its action. An action whose scope has no applied bundle is refused; the other scope's bundle never answers it.

```bash
omnigraph policy validate --target ./company-brain --graph knowledge
omnigraph policy test --tests policy.tests.yaml \
  --target ./company-brain --graph knowledge
omnigraph policy explain \
  --target ./company-brain --graph knowledge \
  --actor act-alice --action read --branch main
```

Edit the policy file or its `applies_to` bindings, then run `cluster apply --target NAME --config DIR` using a registered server target. The server finishes admitted requests before activating matching HTTP and engine permissions. Later requests use the new rules. Cluster management policy changes take effect in the same deployment; a newly granted administrator cannot authorize that grant.

## [Learn your access](/content/docs/operations/policy#learn-your-access/index.html)

`GET /graphs/{graph_id}/access` tells the caller what its own credential may do on a graph, so a client can show only the actions it is allowed instead of learning them from a refusal:

```bash
curl -H "Authorization: Bearer $TOKEN" -H "Omnigraph-Http-Api: 0.14" \
  "https://graph.example/graphs/knowledge/access?branch=feature&target_branch=main"
```

With the example graph policy above, `act-alice` gets:

```json
{"actor_id":"act-alice","graph_id":"knowledge","graph_wide":["read","invoke_query"],"branch":"feature","target_branch":"main","actions":["read"]}
```

- `client_id` appears when the credential is a verified OIDC access token: the OAuth client it was issued to. The actor stays the person's `principal:<id>`, so policy decides alike for every client a person uses.
- `graph_wide` is the decision with no branch named: `invoke_query`, and an action one rule allows on every branch, with no branch scope, `branch_scope: any` or `target_branch_scope: any`. Rules that cover every branch only together, one for protected branches and one for the rest, allow each named branch but not the decision without one, so read `actions` for a branch.
- With `branch`, `actions` lists the actions allowed on it: `read`, `export`, `change` and `maintain` (served optimize asks it on `main`), and `branch_delete`, `commit_publish`, `commit_drop` and `schema_apply` with that branch as their target. Schema apply and the system-column upgrade target `main` only, and a storage upgrade authorizes each live branch, so `schema_apply` on another branch does not make schema apply possible there. `branch_claim` is not listed: no command or route performs it in this release.
- With `target_branch` as well, `actions` also lists `branch_create` from `branch` into the target and `branch_merge` of `branch` into it.

The route evaluates the installed policy for the caller's resolved actor, each action shaped as the route that performs it shapes it, so it answers exactly as those routes decide. It needs no action of its own, reads no graph data, and judges branches by name without checking that they exist. It names actions, never the rules behind them, and reveals nothing about other actors. A credential on a graph without a policy gets nothing (a static token gets `read` when the server sets `OMNIGRAPH_ALLOW_READS_WITHOUT_POLICY=1`), as those routes decide; a server without authentication allows every graph action and reports `actor_id: null`. The MCP `access` tool returns the same body, and `omnigraph access` prints it for a server or managed target ( [what you may do at a target](/content/docs/cli/targets#what-you-may-do-at-a-target/index.html)).

It reports policy actions, not actor views, so a view can still refuse a `change` the policy allows. It does not report `reclaim`, since no server route runs cleanup.

## [Actor identity](/content/docs/operations/policy#actor-identity/index.html)

For HTTP requests, the server maps the bearer token to an actor. Headers, query parameters, and request bodies cannot override that identity. Signed credentials use `principal:<immutable-principal-id>`; groups and permissions come from applied policy. An identity credential contains no graph/action grants. Version-1 restricted credentials are not accepted.

For direct CLI writes, actor resolution is:

1. `--as <ACTOR>`;
2. no actor.

The version-1 operator document has no actor field.

When a policy is installed, a missing actor is denied. Only the server resolves a served write's actor; there `--as` is an assertion the server checks against the token ( [Assert the actor](/content/docs/operations/server#assert-the-actor/index.html)).

Successful graph commits record the actor for the whole atomic change. Inspect the audit trail with:

```bash
omnigraph commit list --target ./graph.omni --json
omnigraph commit show <COMMIT_ID> --target ./graph.omni --json
```

## [Server startup modes](/content/docs/operations/policy#server-startup-modes/index.html)

For static token authentication:

| Tokens       | Policy    | Startup and authorization                                      |
|--------------|-----------|----------------------------------------------------------------|
| none         | none      | Requires explicit `--unauthenticated`; otherwise startup fails |
| configured    | none      | Only the `read` action is allowed; all other actions are denied |
| configured    | configured | The policy decides each action                                    |
| none         | configured | Startup fails because no request could establish an actor      |

`GET /graphs` is denied unless a `cluster`-scoped policy grants `graph_list`, including when graph policies exist.

Signed-token trust also enables authenticated startup. Signed credentials require an explicit policy permit for protected operations even when no static tokens are configured. Only the minimal identity discovery route is independent of policy membership; it exposes existence, not graph access.

Policy is enforced for graph writes inside the engine as well as at the HTTP boundary. This keeps direct and embedded writers subject to the same action checks when a policy engine is installed. Per-entity and per-property authorization is not currently supported; authorization is graph/branch scoped.
