# HTTP server

`omnigraph-server` serves every healthy graph in one applied cluster under `/graphs/{graph_id}/…`. It has no single-graph boot mode. Directory boot reads the current `cluster.yaml` to resolve storage and validate the source location; graph, query, and policy resources come from applied state. URI boot is config-free.

The [OpenAPI document](https://github.com/ModernRelay/omnigraph/blob/main/openapi.json) defines the graph API. A running server returns it from `GET /openapi.json`, which is not self-listed.

## Start a server

From a local cluster bundle:

```bash
OMNIGRAPH_SERVER_BEARER_TOKENS_JSON='{"act-alice":"secret"}' \
  omnigraph-server --cluster ./company-brain --bind 0.0.0.0:8080
```

For object storage, replace `./company-brain` with the cluster root, for example `s3://company-data/omnigraph/company-brain`.

The default bind address is `127.0.0.1:8080`. `--require-all-graphs` makes any graph startup failure fatal. Otherwise failed graphs remain in the authorized inventory as blocked while healthy graphs serve; see [readiness](/content/docs/getting-started/deployment.md).

An applied empty cluster creates no default graph and serves an empty inventory. `/readyz` reports its applied digest, ledger revision/CAS and zero graph counts. Missing or unapplied state, or a nonempty cluster whose graphs all fail, refuses startup. Authentication, policy and data-token root checks still apply.

Use `cluster apply --target NAME --config DIR` with a registered server target for schema, query, policy, provider and Blob-rule changes without restart. Graph additions and removals use the same deployment; removal deletes the graph's managed storage and history. Direct apply requires stopped serving and a subsequent start; see [cluster deployments](/content/docs/clusters.md). An unapplied resource edit does not activate it, although changing or breaking the directory's config can change where boot looks for applied state.

For first boot of a fresh, empty S3 cluster initialized by the library, use `--bootstrap-handoff FILE` with its exact receipt. This is a one-time ownership claim, not a restart or recovery path; see [first boot from a bootstrap receipt](/content/docs/clusters.md#first-boot-from-a-bootstrap-receipt/index.html).

### Logs

Use [server logs and traces](/content/docs/operations/observability.md) for JSON logging, optional OTLP export and correlation with incoming W3C trace context.

## HTTP contract

Refresh the CLI, server and HTTP integrations together ([0.14 release notes](https://github.com/ModernRelay/omnigraph/blob/main/docs/releases/v0.14.0.md)). Every protected request requires exactly one `Omnigraph-Http-Api: 0.14`: graph, registry and cluster-deployment calls, including `/graphs/discovery`, JSON, streams and Blob GET/HEAD. Missing, duplicate, combined or unsupported values return `400 api_contract_mismatch` after authentication but before graph lookup, body decoding or execution. This HTTP identifier is separate from package/storage versions and grants no permission. Earlier prerelease builds also use `0.14`, so header admission cannot detect their older shapes; refresh components together and regenerate SDKs.

Ordinary responses, including errors and streams, carry the same header. Check it before decoding or emitting the body. A missing/incompatible response header means unknown effects, never permission to replay. Proxies must preserve it both ways.

Server URLs name the service root, including its proxy prefix. Select a graph with `--graph`, `default_graph` or `alias.graph`. Migrate graph-qualified server URLs to that root plus graph selection; the CLI never guesses a root from a path. Register the endpoint under `targets:` and select its name with `--target`; inline remote URLs and Unix socket targets are unsupported. Other clients can use a [Unix-socket gateway](/content/docs/getting-started/deployment.md#unix-socket-access/index.html).

Server targets bind a credential owner or anonymous access to an endpoint scope. Every composed route must retain that captured choice. A more specific target with another owner or anonymous access blocks the request before discovery; the CLI never switches credentials to match the nested route.

Public `/healthz`, `/readyz` and `/openapi.json` need no header and identify the contract in their responses. Before every graph, registry or deployment request, the CLI sends `HEAD /healthz` to that base with a five-second bound, no bearer, body consumption or cache. Failure prevents data dispatch. Each request adds one discovery round trip; its existing deadline stays separate. Neither request follows redirects or retries automatically. Older clients/servers without this contract are unsupported.

MCP/OAuth metadata neither require nor return this header; managed control-plane APIs keep their separate protocol.

## Authentication

Choose one static token source:

| Environment variable                        | Value                                                                                                                                                                                                         |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OMNIGRAPH_SERVER_BEARER_TOKEN`             | One bearer token; actor is `default`                                                                                                                                                                          |
| `OMNIGRAPH_SERVER_BEARER_TOKENS_JSON`       | Actor-to-token object, e.g. `{"act-alice":"secret-a"}`                                                                                                                                                        |
| `OMNIGRAPH_SERVER_BEARER_TOKENS_FILE`       | Path to that JSON object. On Unix a file other accounts can write is refused at startup, and one they can read logs a warning; use `chmod 600`, or `defaultMode: 0400` on a Kubernetes secret volume          |
| `OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET` | Secrets Manager mapping; requires an AWS-enabled build: the container images, the release archives from v0.14.0 and every edge build, or a source build with `cargo build -p omnigraph-server --features aws` |

Every source refuses a blank actor, a duplicate token value and an actor name starting with `principal:`, which is reserved for signed and OIDC identities (`principal:<id>`), so a static token cannot match their policy rules.

Send `Authorization: Bearer secret-a` (the scheme is case-insensitive). The token selects the actor for authorization and commit attribution; clients cannot claim another actor. See [Authorization and actors](/content/docs/operations/policy.md). Every 401 carries a `WWW-Authenticate: Bearer` challenge, with `error="invalid_token"` when the server refused the token sent; a valid OIDC token it does not admit gets 403 ([MCP](/content/docs/operations/mcp.md)).

A server with neither static tokens, signed-token trust, nor policy refuses to start unless you explicitly pass `--unauthenticated` (or set `OMNIGRAPH_UNAUTHENTICATED=1`). Use that only on a trusted development network. A graph without an applied policy refuses every action to every token, reads included: bearer tokens are not scoped to graphs, so a permit there would reach every graph that lacks a policy. Apply a [graph policy](/content/docs/operations/policy.md) to each graph a token should reach. Setting `OMNIGRAPH_ALLOW_READS_WITHOUT_POLICY=1` in the server's environment restores the earlier behaviour, in which every static token may `read` every graph without a policy; the server logs a warning at startup when it is set.

### Assert the actor

A client that means to act as a particular actor sends `Omnigraph-If-Actor: <actor>` with any protected request, `/mcp` included. After authentication and the contract check (on `/mcp`, before admission), and before graph lookup or any effect, a match changes nothing and a mismatch is `412 actor_mismatch` with nothing run; a server without authentication resolves no actor. A repeated, padded or empty header is `400 bad_request`. The header never supplies the actor, and a server with an incompatible HTTP contract refuses that contract first. The CLI sends it for `--as` on served writes, served `cluster plan` and `apply`, and every [`mcp`](/content/docs/operations/mcp.md#connect-a-stdio-agent/index.html) request.

### Signed data credentials

To accept short-lived credentials from an issuer, mount its public trust file and select it explicitly:

```bash
omnigraph-server --cluster s3://company-data/company-brain \
  --data-token-trust /run/omnigraph/data-token-trust.json
```

The file binds public signing keys to the exact storage root, issuer, account, cluster id, and cluster incarnation. Invalid trust or a root mismatch refuses startup before graphs open. Trust alone requires bearer authentication. The server verifies tokens locally; it does not contact an identity or control service. The provisioning operator owns supplying the correct identity binding. The [trust and credential format](https://github.com/ModernRelay/omnigraph/blob/main/docs/rfcs/0053-offline-data-token-verification.md#public-trust-and-root-binding) defines the machine-written file.

Signed credentials use the actor `principal:<immutable-principal-id>`. A caller cannot change its actor through request headers or JSON. The server accepts version-2 identity credentials, which bind the principal to the cluster and contain no permissions. Applied Cedar policy decides graph operations; missing policy or an unknown policy actor denies protected access.

Every valid identity credential can call `GET /graphs/discovery` for applied graph IDs and names (currently identical), including blocked graphs. It requires no policy membership and returns no locations, availability, schema, queries or data. Static credentials cannot use it. `GET /graphs` requires `graph_list` permission. Discovery grants no graph access or reachability.

See [managed data access](/content/docs/cli/managed-data.md) for issuance and CLI discovery.

Tokens live for 60–86,400 seconds from issuance. The server permits an issuance clock up to 30 seconds ahead, so at most 86,430 seconds can remain on admission. Expiry has no grace period. Logout or a permission change at the issuer does not revoke an issued token; already accepted operations can finish after expiry. Stored-query calls need `invoke_query` plus `read` or `change` for the body. Apply policy changes through `cluster apply --target`; editing a source file alone does not change permissions. Deployment uses [current-policy authorization](/content/docs/operations/policy.md#actions/index.html); the identity credential supplies no bypass.

Static credentials can coexist for operator recovery. An exact configured static credential keeps its existing authority, including credentials with dots; an invalid signed credential never falls back to static or anonymous access. Restart to change public trust. Install new and old keys together before issuing with a new key, and retain the old key for at least 86,430 seconds after its final issuance before removing it with another restart.

### OIDC resource identities and MCP

Enable OIDC with a public admission file alongside signed or static credentials:

```bash
omnigraph-server --cluster s3://company-data/company-brain \
  --oidc-identity-trust /run/omnigraph/provider-access.json
```

The file binds an exact HTTPS issuer, resource audience, organization, account, cluster incarnation and canonical root. Public RSA keys verify RS256 tokens; explicit subject mappings select stable `principal:<id>` actors. Tokens carry no graph permissions: applied Cedar governs graph and schema operations, while every admitted identity can discover graph IDs and names.

Human access tokens must name exactly one configured resource audience, the configured organization and an admitted subject, and expire within 300 seconds of issuance. OAuth-client ID tokens, delegated or impersonated credentials and unqualified machine identities refuse. Every refresh must request the exact resource again and check the returned audience.

Supply at most four RSA keys, 1,000 subject mappings and 256 KiB per public file. The [resource identity contract](https://github.com/ModernRelay/omnigraph/blob/main/docs/rfcs/2026-09-09-identity-credentials-and-applied-policy.md#provider-native-access-and-standard-clients) defines the versioned format. Authority is held by whoever can publish this file; it contains no provider secret or graph policy. Protect its filesystem permissions and publish complete updates atomically.

Boot validates identity and root before opening graphs. Local refresh runs every five seconds: the binding stays fixed, revisions increase, and equal revisions require identical bytes. Every request checks the original snapshot deadline, at most 300 seconds after capture; invalid updates cannot extend it. Requests never fetch keys or call a control service, so publisher outages eventually prevent new OIDC access; accepted operations can finish. Admission refresh does not restart writers. Graph configuration retains its normal activation.

With this profile configured, the server also serves public protected-resource metadata and names it in every 401's challenge, so standard OAuth clients such as Claude can sign in. The [MCP guide](/content/docs/operations/mcp.md) describes sign-in, which resource identifier to choose, and the endpoint's tools, settings and limits.

## Route families

| Route family                                                                    | Purpose                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /healthz`                                                                  | Process health                                                                                                                                                                                                                                                                                                                      |
| `GET /readyz`                                                                   | Replica readiness and booted applied revision                                                                                                                                                                                                                                                                                       |
| `GET /openapi.json`                                                             | Runtime copy of the OpenAPI document                                                                                                                                                                                                                                                                                                |
| `GET /graphs`                                                                   | Graph metadata catalog; requires `graph_list` policy                                                                                                                                                                                                                                                                                |
| `GET /graphs/discovery`                                                         | Graph IDs and display names only; requires an identity credential                                                                                                                                                                                                                                                                   |
| `POST /cluster/plan`                                                            | Preview source changes against the running cluster without applying them                                                                                                                                                                                                                                                            |
| `POST /cluster/deployments`                                                     | Submit an exact-ID deployment: graph creation/deletion or schema, query, policy, provider and Blob-binding changes                                                                                                                                                                                                                  |
| `GET /cluster/deployments`, `GET /cluster/deployments/{deployment_id}`          | Authorized deployment status and current-process activation observation                                                                                                                                                                                                                                                             |
| `GET /.well-known/oauth-protected-resource`, also at the resource's path suffix | Public OIDC resource metadata; only when OIDC trust is configured                                                                                                                                                                                                                                                                   |
| `/mcp`                                                                          | The [MCP endpoint](/content/docs/operations/mcp.md); when static tokens, signed data tokens or OIDC trust are configured                                                                                                                                                                                                                       |
| `/graphs/{graph_id}/query`, `/mutate`                                           | Run inline GQ source                                                                                                                                                                                                                                                                                                                |
| `/graphs/{graph_id}/mutate/if-graph-commit`                                     | Run an inline conditional mutation                                                                                                                                                                                                                                                                                                  |
| `/graphs/{graph_id}/queries`                                                    | List and invoke stored queries, including conditional mutations                                                                                                                                                                                                                                                                     |
| `/graphs/{graph_id}/load`, `/load/ndjson`                                       | Bounded batch loading                                                                                                                                                                                                                                                                                                               |
| `/graphs/{graph_id}/blob`                                                       | GET/HEAD one Blob cell; PUT/DELETE to replace or clear it                                                                                                                                                                                                                                                                           |
| `/graphs/{graph_id}/branches`                                                   | Branch management and merge, a detailed listing (`GET /branches?detailed=true`), a merge dry run (`dry_run: true`), a branch's diff against its merge base (`GET /branches/diff`) and that merge base (`GET /branches/merge-base`)                                                                                                  |
| `/graphs/{graph_id}/snapshot`, `/commits`                                       | Snapshot (`internal_schema_version`, `graph_manifest_version`, and the datasets of one captured graph version), history (paged with `limit` and `page_token`), per-commit changes, and the unpublished commits of a branch (`GET /commits?listing=unpublished`, `POST /commits/{commit_id}/publish`, `DELETE /commits/{commit_id}`) |
| `/graphs/{graph_id}/changes`, `/diff`                                           | Poll a branch feed, establish a baseline, or diff two points (branches or commit ids)                                                                                                                                                                                                                                               |
| `/graphs/{graph_id}/schema`                                                     | Show the accepted schema                                                                                                                                                                                                                                                                                                            |
| `GET /graphs/{graph_id}/access`                                                 | The caller's own actor and the actions its credential allows; see [Learn your access](/content/docs/operations/policy.md#learn-your-access/index.html)                                                                                                                                                                                                    |
| `/graphs/{graph_id}/export`                                                     | Stream a branch snapshot as JSONL                                                                                                                                                                                                                                                                                                   |

`/query` also serves `branch list`, the branch reads (`branch diff`, `branch merge-base`, `branch merge … dry run`), `show`, and [explain](/content/docs/queries-search/explain.md).
`/mutate` serves `branch create`, `branch delete`, `branch merge`, `commit publish`, and `commit drop`. See [Branching](/content/docs/branching.md). Each of `/query`, `/mutate`, `/mutate/if-graph-commit` and `/branches/merge` takes an optional `settings` field, and the two GET change routes a `set=` parameter; see [Session settings](/content/docs/queries-search/queries.md#session-settings/index.html).

## Run an inline query

```bash
curl -sS http://localhost:8080/graphs/knowledge/query \
  -H 'Omnigraph-Http-Api: 0.14' \
  -H 'authorization: Bearer secret-a' \
  -H 'content-type: application/json' \
  -d '{
    "query":"query find($name: String) { match { $p: Person { name: $name } } return { $p.name } }",
