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

# OmniRoute

> Connect OmniRoute to Openference via OAuth (PKCE) or device flow.

# OmniRoute

[OmniRoute](https://github.com/diegosouzapw/OmniRoute) is an open-source AI proxy and router. Use **Sign in with Openference** to route chat completions through `api.openference.com` with your Openference account and plan.

## OAuth client

| Field                  | Value                                                          |
| ---------------------- | -------------------------------------------------------------- |
| Client ID              | `omniroute`                                                    |
| Discovery              | `GET https://openference.com/.well-known/openid-configuration` |
| Authorize (hosted SPA) | `https://openference.com/app/oauth/authorize`                  |
| Token                  | `POST https://openference.com/oauth/token`                     |
| API base               | `https://api.openference.com/v1`                               |
| Scopes                 | `openid profile email model:invoke offline_access`             |

OmniRoute uses **PKCE** with a loopback redirect (`http://127.0.0.1:<port>/callback` or `http://localhost:<port>/callback`). The `omniroute` client is first-party: after the first approval, consent is remembered.

Access tokens are **ES256 JWTs** (1 hour TTL). Refresh tokens use the `oar_*` prefix and **rotate on every use** — reuse revokes the whole family.

## Account and plan requirements

* You need an **Openference user account**. If you sign in with Google/GitHub and have never registered, create an account from the authorize or device page.
* OAuth JWTs authenticate API requests. Users **without an active plan** may receive **402** on inference endpoints (`/v1/chat/completions`, etc.) even when auth succeeds.

## Device flow (headless / VPS)

When loopback PKCE is not available (remote OmniRoute install), the `omniroute` client also supports **RFC 8628 device authorization**:

1. `POST https://openference.com/oauth/device` with `client_id=omniroute` and scope `openid profile email model:invoke offline_access`
2. Open `verification_uri_complete` in a browser (or visit `/app/oauth/device` and enter the user code)
3. Sign in or **create an account**, then approve
4. Poll `POST /oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`

## Manual smoke (after deploy)

```bash theme={null}
# 1. Complete PKCE in the OmniRoute dashboard (Connect Openference), or approve via API in staging.
# 2. Exchange code for tokens, then:
curl -sS https://api.openference.com/v1/models \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS https://api.openference.com/v1/chat/completions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"GLM-5.2","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'
```

Expect **200** with an active plan, or **402** without one — not **401** if the JWT is valid.

## API key alternative

You can also add Openference as a custom OpenAI-compatible provider with an API key from the [dashboard](https://openference.com/dashboard). OAuth is recommended for dashboard installs that support browser sign-in and automatic token refresh.