# Authentication And Authorization Map

Omnius has two separate credential boundaries:

1. provider credentials authenticate Omnius to an inference provider; and
2. REST bearer credentials authenticate a caller to the Omnius daemon.

Do not reuse one boundary as the other in new deployments.

## Provider Credentials

Upstream inference credentials resolve in this exact order:

```text
OMNIUS_PROVIDER_API_KEY
  → OMNIUS_MODEL_API_KEY
  → OMNIUS_UPSTREAM_API_KEY
  → OMNIUS_API_KEY
  → VLLM_API_KEY
  → persisted endpoint configuration
```

The first defined value wins. `OMNIUS_API_KEY` is retained as a legacy
provider and REST fallback; prefer the explicit provider namespace.

The resolved value is applied according to the registered provider protocol:

| Protocol/provider | Authentication |
| --- | --- |
| `ollama` | none by default |
| local `openai-chat` | optional `Authorization: Bearer` |
| cloud `openai-chat` | `Authorization: Bearer <provider-key>` |
| Gemini | Bearer plus `x-goog-api-client: omnius/<version>` |
| `anthropic-messages` | `x-api-key: <provider-key>` plus `anthropic-version` |
| sponsor/COHERE | peer/session policy; upstream secrets stay provider-side |

Provider credentials must never appear in endpoint URLs, discovery documents,
logs, process output, sponsor metadata, or client-visible errors.

## REST Daemon Credentials

Preferred environment variables:

```text
OMNIUS_REST_API_KEY
OMNIUS_REST_API_KEYS
```

Compatibility variables:

```text
OMNIUS_API_KEY
OMNIUS_API_KEYS
```

Multi-key format:

```text
key:scope:owner:rpm:tpd:max_jobs
```

The daemon also accepts persistent runtime keys stored under
`~/.omnius/keys.json` by default and a local bootstrap key under
`~/.omnius/api.key`. Runtime keys are minted, listed in masked form, and
revoked through `/v1/keys`.

Send daemon credentials only in:

```text
Authorization: Bearer <key>
```

Query-string credentials are rejected because URLs leak into browser history,
logs, and telemetry.

## Scopes

| Scope | Typical authority |
| --- | --- |
| `read` | health/version, discovery, models, config summaries, tools/skills metadata, memory search, usage, events |
| `run` | chat, runs, permitted tool calls, allowed memory writes |
| `admin` | config/key/profile mutation, high-risk controls, admin tools |

Scope is necessary but not sufficient for a tool call. Tool security metadata,
the selected profile, request origin, off-device policy, network policy, and
risk classification are enforced after bearer authentication.

## Profiles And External Tools

Runtime keys may bind a named tool profile. A run key with a bookkeeping
profile can update todos and notes without receiving filesystem, shell, or
network tools.

HTTP- and MCP-backed external tools use the same daemon auth, policy, audit,
and direct-call metadata as built-in tools. Registration requires run scope
locally and admin scope for remote callers.

## Routes Without Work Authority

Health, version, help, OpenAPI, and discovery remain accessible for
compatibility diagnosis according to daemon binding/auth configuration.
Reading capability metadata does not grant authority to execute it.

The optional `X-Omnius-Min-Version` header is a package compatibility
precondition, not authentication. A valid bearer key does not bypass a stale
service rejection, and satisfying the version gate does not grant a scope.

## Network Deployment Rules

- Keep the default loopback binding for personal use.
- Require scoped bearer keys before binding to LAN or public interfaces.
- Put internet-facing daemons behind TLS and a narrow reverse-proxy allowlist.
- Use a distinct key and narrow tool profile for each agent/service.
- Strip REST key variables before spawning model-facing subprocesses.
- Redact provider and REST credentials before sending context to remote
  inference, sponsor, COHERE, Telegram, or MCP peers.

See [Auth And Scopes](../rest/auth-and-scopes.md) for request examples and
[Security And Remote Access](../operations/security-and-remote-access.md) for
deployment hardening.