> ## Documentation Index
> Fetch the complete documentation index at: https://onr.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Key (onr:v1?)

> Single-key auth format for clients that cannot set custom headers.

Token Key is an authentication format designed for clients that can only supply a single API key value and cannot add extra headers.

You send it as:

`Authorization: Bearer onr:v1?...`

## When to use

* Your client can only configure a single key field (no extra headers)
* You still want ONR access-key auth, plus optional provider/model pinning
* You want an opt-in BYOK path (use an upstream key supplied by the client)

If your client can send headers normally, prefer a plain access key:

`Authorization: Bearer <ACCESS_KEY>`

## Format

Token Key is a URI-like string:

* `onr:v1?k=<ACCESS_KEY>&...`
* `onr:v1?k64=<base64url(ACCESS_KEY)>&...` (recommended)

`ACCESS_KEY` must match a client access key from `keys.yaml` (`access_keys[].value`), after env override and optional decryption.

## Query parameters

| Param  | Required                  | Meaning                                                                               |
| ------ | ------------------------- | ------------------------------------------------------------------------------------- |
| `k`    | yes (or `k64`) by default | Access key (plaintext).                                                               |
| `k64`  | yes (or `k`) by default   | Access key encoded as base64url. Recommended to avoid URL escaping issues.            |
| `p`    | no                        | Force provider selection (bypasses normal provider routing).                          |
| `m`    | no                        | Force model override. When present, ONR enforces it (replaces the request model).     |
| `uk`   | no                        | BYOK upstream key (plaintext). When present, ONR uses it directly for upstream calls. |
| `uk64` | no                        | BYOK upstream key encoded as base64url. Recommended to avoid URL escaping issues.     |

If you explicitly enable:

```yaml theme={null}
auth:
  token_key:
    allow_byok_without_k: true
```

then BYOK token keys with only `uk` / `uk64` are allowed.

## Examples

Force provider:

`onr:v1?k64=...&p=openai`

Force model:

`onr:v1?k64=...&m=gpt-4o-mini`

BYOK + provider + forced model (plaintext upstream key):

`onr:v1?k64=...&p=openai&uk=sk-xxx&m=gpt-4o-mini`

BYOK + provider + forced model (base64url upstream key):

`onr:v1?k64=...&p=openai&uk64=...&m=gpt-4o-mini`

## Generate token keys

Use `onr-admin` to securely generate these tokens from your CLI without manually base64-encoding strings:

```bash theme={null}
onr-admin token create \
  --config ./onr.yaml \
  --access-key-name client-a \
  --provider openai \
  --model gpt-4o-mini
```

See [Admin CLI](/ecosystem/admin-panel) for more commands and the web dashboard usage.

## Security notes

* **Tamperable By Design**: Token Key is intentionally editable (no cryptographic signature). Treat it like a pure bearer secret.
* **Base64 Safety**: Avoid putting plaintext secrets into URLs when possible. Prefer `k64` / `uk64` to reduce accidental escaping or logging issues, but note they are still secrets (Base64 is not encryption).
* **BYOK Risks**: If you enable BYOK (`uk` / `uk64`), clients can supply their own upstream key. Consider whether that is acceptable for your deployment and logging policy.