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:

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:

onr-admin token create \
  --config ./onr.yaml \
  --access-key-name client-a \
  --provider openai \
  --model gpt-4o-mini

See Admin CLI 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.