# 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. Prefer `OMNIUS_PROVIDER_API_KEY`, `OMNIUS_MODEL_API_KEY`, or provider-native variables such as `VLLM_API_KEY` for upstream model auth. `OMNIUS_API_KEY` remains a legacy fallback for provider auth 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` and are checked after environment keys.

| 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",
  "owner": "ci",
  "profile": "readonly",
  "rpm": 60,
  "tpd": 100000,
  "max_jobs": 3
}
```

## 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.
