# Auth And Scopes

Omnius can run without auth for local development, but shared deployments should use bearer keys.

## Environment Keys

Single admin key:

```bash
OMNIUS_REST_API_KEY="admin-secret" omnius serve
```

Multiple scoped keys:

```bash
OMNIUS_REST_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve
```

Format:

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

Compatibility: `OMNIUS_API_KEY` and `OMNIUS_API_KEYS` are still accepted as legacy REST auth variables, but new deployments should use the `OMNIUS_REST_*` namespace.

Provider keys are separate from REST keys. The exact upstream precedence is
`OMNIUS_PROVIDER_API_KEY` → `OMNIUS_MODEL_API_KEY` →
`OMNIUS_UPSTREAM_API_KEY` → `OMNIUS_API_KEY` → `VLLM_API_KEY` → persisted
endpoint configuration. `OMNIUS_API_KEY` remains a legacy fallback for both
provider and legacy REST auth, so avoid it in new remote deployments. Scoped
REST keys (`OMNIUS_REST_*` and `OMNIUS_API_KEYS`) are stripped before spawning
agent subprocesses and are not forwarded as model-provider credentials.

Fields:

- `key`: bearer token.
- `scope`: `read`, `run`, or `admin`.
- `owner`: audit label.
- `rpm`: optional requests-per-minute cap.
- `tpd`: optional tokens-per-day cap.
- `max_jobs`: optional concurrent job cap.

## Runtime Keys

Runtime keys are stored under `~/.omnius/keys.json` by default and are checked after environment keys and the local bootstrap key. Override the store with `OMNIUS_RUNTIME_KEYS_FILE` or put all Omnius state under another directory with `OMNIUS_CONFIG_HOME`.

Global installs create a local daemon bootstrap key at `~/.omnius/api.key` if one does not exist. The daemon accepts it as an admin token, so a local operator can start Omnius and run `/apikey show` to reveal it, or `/apikey mint run` to create a project runtime key.

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| `GET` | `/v1/keys` | admin | List masked runtime keys |
| `POST` | `/v1/keys` | admin | Mint a key; response contains the full secret once |
| `DELETE` | `/v1/keys/{prefix}` | admin | Revoke keys matching a prefix |

Mint body:

```json
{
  "scope": "run",
  "project": "myactuator",
  "owner": "project:myactuator",
  "profile": "readonly",
  "rpm": 60,
  "tpd": 100000,
  "max_jobs": 3
}
```

If `owner` is omitted and `project` is provided, Omnius uses `project:<project>` as the audit owner.

Agent and MCP-style clients should persist the returned secret in their own secret store and send it as:

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

Do not put API keys in query strings. Omnius rejects query-string keys to keep them out of logs and browser history.

## Scope Semantics

`read` is for inspection:

- health, version, metrics
- models
- config summaries
- usage, cost, audit reads
- skills and tools metadata
- memory search
- events

`run` can execute:

- `/v1/run`
- run-scope tools
- memory writes where allowed
- chat and agentic endpoints

`admin` can mutate:

- config
- runtime keys
- profiles
- admin-only tools
- AIMS policy registers
- high-risk local controls

Tool calls are additionally gated by each tool's security metadata. Scope alone is not the only control.

Runtime keys may bind a tool profile. A run-scope key with profile `bookkeeping-tracking` can update todos and notes but cannot expose or execute filesystem/search/shell tools.

## Request Header

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

## Network Access

For local development, bind to loopback. For remote access, set explicit auth and access policy:

```bash
OMNIUS_HOST=0.0.0.0:11435 OMNIUS_REST_API_KEYS="run-key:run:remote" omnius serve
```

Do not expose an unauthenticated daemon on a public interface.