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

# Keys

> RouterBase has three kinds of keys. Pick the right one for your use case.

RouterBase has **three kinds of keys**. They look similar, do different things, and mixing them up is the single most common mistake when integrating.

## The three kinds at a glance

| Kind                          | Prefix                   | Holds it                        | Purpose                                                                                                         |
| ----------------------------- | ------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **API Key**                   | `sk-rb-…`                | Your end users (or you)         | Calls models: chat, images, videos, audio                                                                       |
| **Management API Key**        | `sk-rb-prov-…`           | Your SaaS backend / ops scripts | Creates, rotates, and revokes API keys programmatically — cannot call models                                    |
| **BYOK** (Bring Your Own Key) | *opaque upstream secret* | You, registered once            | Lets RouterBase call upstream providers (OpenAI / Anthropic / Google) using **your** credential instead of ours |

## Which one do I need?

> "I'm just trying RouterBase out."
> → **API Key**. Get one on [the dashboard](https://routerbase.com/api-key), put it in `Authorization: Bearer`, done.

> "I'm building a product on top of RouterBase and want one key per end-user of my product."
> → **Management API Key**. Keep it server-side; use it to mint a fresh **API Key** per signup. Each user gets their own rate limits and can be revoked independently.

> "I already pay OpenAI / Anthropic / Google directly and want my RouterBase calls to bill against my existing account, not RouterBase's."
> → Register a **BYOK credential**. Your API Key still authenticates you *into* RouterBase; outbound calls to that provider use your upstream credential.

> "I want all three."
> → Supported. None of them are exclusive.

## How they fit together

```
                                                       ┌──────────────┐
                                                       │   Upstream   │
                                                       │   Provider   │
                                                       │ (OpenAI,     │
                                                       │  Anthropic,  │
                                                       │  Google)     │
                                                       └──────▲───────┘
                                                              │
                                   platform key (ours)        │
                                   ─────── OR ───────         │
                                   BYOK (your key, stored     │
                                   once)                      │
                                                              │
  ┌──────────────┐ sk-rb-prov-…    ┌────────────────────┐     │
  │  Your SaaS   │                 │   RouterBase       │     │
  │  backend /   │ ──────────────▶ │                    │     │
  │  ops scripts │ CRUDs API keys  │  /api/v1/keys      │     │
  └──────────────┘                 │                    │     │
                                   │                    │     │
  ┌──────────────┐ sk-rb-…         │  /v1/chat/…        │     │
  │  End user    │                 │  /v1/images/…      │─────┘
  │  (or you)    │ ──────────────▶ │  /v1/videos/…      │
  └──────────────┘ calls models    │  /v1/audio/…       │
                                   └────────────────────┘
```

* **Arrows going in** to RouterBase — your **API Key** or **Management API Key**. Both live in the `Authorization` header, different prefixes.
* **Arrows going out** of RouterBase — your **BYOK credential**. Never appears in an `Authorization` header to RouterBase; stored once, used outbound when RouterBase calls the upstream provider on your behalf.

## Strict separation

Middleware rejects the wrong kind on the wrong route with `403`:

* A **Management API Key** on `/v1/chat/completions` (or any completion / media route) → `403` "Management keys cannot call completion endpoints". There is no bypass.
* An **API Key** on `/api/v1/keys` (the CRUD endpoint used by Management keys) → `403`.

## Using your API Key

Include it as a Bearer token in every request:

```http theme={null}
Authorization: Bearer sk-rb-xxxxxxxxxxxx
Content-Type: application/json
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://routerbase.com/v1/chat/completions \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-2.5-flash",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-rb-xxxxxxxxxxxx",
      base_url="https://routerbase.com/v1",
  )

  resp = client.chat.completions.create(
      model="google/gemini-2.5-flash",
      messages=[{"role": "user", "content": "Hello"}],
  )
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "sk-rb-xxxxxxxxxxxx",
    baseURL: "https://routerbase.com/v1",
  });

  const resp = await client.chat.completions.create({
    model: "google/gemini-2.5-flash",
    messages: [{ role: "user", content: "Hello" }],
  });
  ```
</CodeGroup>

Each key is displayed **only once** at creation time — copy it immediately. Full CRUD: [API Keys reference](/api-reference/api-keys).

## Using a Management API Key

Mint one through the logged-in dashboard (JWT-authed root of trust — Management keys cannot mint other Management keys). Then use it server-side to create API keys for your end-users:

```bash theme={null}
curl -X POST https://routerbase.com/api/v1/keys \
  -H "Authorization: Bearer sk-rb-prov-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_12345 production key", "rate_limit_rpm": 60}'
# → returns the plaintext API key once; hand it to your end user
```

## Security

<Warning>
  * Never embed any of these keys in frontend code, browser JavaScript, or mobile apps.
  * Never share a **Management API Key** with end-users — it can mint and revoke keys on your entire account.
  * Never share a **BYOK credential** — it charges your upstream provider account.
</Warning>

* Store keys in environment variables or a secrets manager (AWS Secrets Manager, Vault, etc.).
* Use IP whitelisting to restrict API Keys to your server IPs.
* Rotate keys regularly. `disabled=true` pauses; `DELETE` revokes permanently.