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

# Router authentication

> How router keys, provider subscriptions, and SSO fit together

Weave Router uses two independent credentials: a **router key** that identifies your organization to Weave, and your **provider credentials** that pay for the inference. They travel in different headers and never replace each other.

## The two credentials

| Credential | Looks like | What it does |
| - | - | - |
| Weave Router key | `rk_…` | Identifies your org and engineer to Weave. Sent as `X-Weave-Router-Key`. |
| Provider subscription or key | OAuth token, `sk-…` | Pays for the turn when it runs on your own plan or your own provider account. |

<Warning>
  A router key is **not** an Anthropic or OpenAI API key. Installing the router does not move you onto per-API billing. If your requests suddenly bill per API call, the cause is almost always a provider API key set in your environment — see [subscription pass-through](#subscription-pass-through) below.
</Warning>

## Issuing and managing keys

Org admins manage keys in the **Active router keys** panel at the top of [router settings](https://app.workweave.ai/organization/settings/weave-router).

* **Issue** a key per engineer or per environment. Name it so you can tell them apart later.
* **Spend cap** — set an optional per-key dollar cap at issue time or later. It's a lifetime cap, not a monthly one: once the key's paid spend reaches it, paid requests on that key get a 402 until you raise the cap or issue a new key. Leave it blank for uncapped.
* **Rotate** — replaces the token. The old one stops working, so re-run the installer with the new key.
* **Revoke** — the token stops working immediately.

The full token is shown **once**, at issuance or rotation, together with the install one-liners. Weave stores only a hash, so a lost key must be rotated.

Non-admin members can see the org's active keys but cannot issue, rotate, or revoke them.

## Subscription pass-through

When your engineers are on a Claude (Pro, Max, Team, Enterprise) or ChatGPT/Codex subscription, the router forwards their existing provider credentials upstream, so plan-covered turns bill to the plan and consume no Weave credits.

For Claude Code this requires:

* Claude Code signed in with your Claude subscription, which the installer leaves alone so its OAuth token still pays for the call (`CLAUDE_CODE_OAUTH_TOKEN` works too, but isn't required)
* `ANTHROPIC_API_KEY` **not** set — if it is, Claude Code uses it and you get per-API billing
* The router installed with your `rk_…` key, which only adds the base URL and the key header

<Note>
  Because subscription turns are paid by the plan, your credit balance can stay flat while usage is heavy. That is expected, not a reporting bug. To price your workload as if the subscription didn't exist, switch subscription routing to **Use prepaid credits only** in [models and routing](/router/models-and-routing#subscription-routing).
</Note>

## Signing in to the router dashboard

[router.workweave.ai](https://router.workweave.ai) supports GitHub, Google, and SAML/OIDC single sign-on (SSO). SSO is the same configuration used by the main Weave app — see [SSO](/settings/sso). Sign-in is for the dashboard only; agent traffic authenticates with the router key, not a browser session.

<Note>
  Machine-to-machine identity federation — registering your own OIDC issuer, or exchanging an identity-provider token for a router credential — is not available today. Provision router keys through your secret manager for VM, container, and CI environments, and set `WEAVE_ROUTER_KEY` in the environment before running the installer with `--non-interactive`.
</Note>

## Using your own provider keys

You can run inference on your own provider accounts instead of Weave's. Add a key per provider under **Billing & spend → Your provider keys**. Requests then bill to your provider account directly and Weave charges a platform fee against your credit balance. See [bring your own keys](/router/billing#bring-your-own-provider-keys).

If those requests go through an enterprise gateway rather than the vendor — Snowflake Cortex, a private-cloud deployment, an internal proxy — see [custom endpoints and gateways](/router/custom-endpoints), which also covers gateways that authenticate with an RSA key pair instead of a token.

## Calling the router directly

Any client that speaks the Anthropic Messages, OpenAI Chat Completions, or Gemini `generateContent` API can use the router without the installer. Send your key as a bearer token or in the `X-Weave-Router-Key` header:

```bash theme={null}
curl https://router.workweave.ai/v1/messages \
  -H "Authorization: Bearer rk_..." \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":1024,
       "messages":[{"role":"user","content":"hi"}]}'
```

The OpenAI-compatible surfaces are `https://router.workweave.ai/v1/chat/completions` and `https://router.workweave.ai/v1/responses`, and Cursor-style clients use `https://router.workweave.ai/v1` as the base URL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.