> ## 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.

# API Keys

> Create, list, update, and revoke General API Keys — the keys your end users hold to call completion endpoints.

API Keys authenticate into `/v1/chat/completions`, `/v1/images/generations`, `/v1/videos/generations`, and `/v1/audio/*`. If you just want to understand RouterBase's keys at a high level, start with [Keys](/essentials/keys).

**Authentication for these endpoints:** JWT (logged-in dashboard session).

## Key format

```
sk-rb-<public_id:12>-<secret:48>
```

The `public_id` is safe to log / display (it's the URL slug used in rate-limit lookups). The secret half is returned **only once** at create time — never shown again.

***

## List API Keys

```
GET https://routerbase.com/api/v1/api-keys
```

Returns all API Keys for the authenticated user, newest first. `key_prefix` is always a masked display string (`first12…last4`). `full_key` carries the full plaintext **only for keys minted after plaintext persistence shipped** — legacy keys omit the field, keeping their secret half unavailable.

### Example

```bash theme={null}
curl https://routerbase.com/api/v1/api-keys \
  -H "Authorization: Bearer <JWT>"
```

### Response

```json theme={null}
[
  {
    "id": "3c7b3fd5-2563-4d81-847d-1138ed431654",
    "name": "production",
    "key_prefix": "sk-rb-kN2lOa...WL1x",
    "full_key": "sk-rb-kN2lOa7oIlOw-P938cWHaSZi7Z0shwtFMOl0EY089FGBBN6qPeIWL1xODJBle",
    "ip_whitelist": [],
    "rate_limit_rpm": 60,
    "rate_limit_tph": null,
    "rate_limit_tpd": null,
    "is_provisioning": false,
    "disabled": false,
    "created_by": null,
    "created_at": "2026-04-24T10:00:00Z",
    "credit_limit": null,
    "credit_reset_interval": "none",
    "credit_used": 0.0,
    "credit_period_start": null,
    "expires_at": null
  }
]
```

| Field                   | Notes                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `full_key`              | Full plaintext key. Present only for keys minted after plaintext persistence; omitted for legacy keys. |
| `is_provisioning`       | `true` for Management API Keys (`sk-rb-prov-…`), `false` for regular API Keys.                         |
| `credit_limit`          | USD spend cap, or `null` for unlimited.                                                                |
| `credit_reset_interval` | `none` \| `daily` \| `weekly` \| `monthly`.                                                            |
| `credit_used`           | USD spent in the current period (for "used / limit" display).                                          |
| `credit_period_start`   | Start of the current spend window, or `null` when no limit is set.                                     |

***

## Create API Key

```
POST https://routerbase.com/api/v1/api-keys
```

### Request Body

<ParamField body="name" type="string" required>
  A human-readable label for the key.
</ParamField>

<ParamField body="rate_limit_rpm" type="number">
  Max requests per minute. No limit if omitted.
</ParamField>

<ParamField body="rate_limit_tph" type="number">
  Max tokens per hour. No limit if omitted.
</ParamField>

<ParamField body="rate_limit_tpd" type="number">
  Max tokens per day. No limit if omitted.
</ParamField>

<ParamField body="ip_whitelist" type="string[]">
  Up to 10 allowed IPs (IPv4 / CIDR). Empty array or omitted means no restriction.
</ParamField>

<ParamField body="credit_limit" type="number">
  USD spend cap for the key. Omit or `null` for unlimited. Once the cap is hit within the current period the key returns 403 until the period resets.
</ParamField>

<ParamField body="credit_reset_interval" type="string">
  How the spend window rolls over: `none` (default), `daily`, `weekly`, or `monthly`. Only meaningful alongside `credit_limit`.
</ParamField>

<ParamField body="expires_at" type="string (ISO 8601)">
  Optional auto-disable cutoff. After this moment the key returns 401.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://routerbase.com/api/v1/api-keys \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "rate_limit_rpm": 60,
    "ip_whitelist": ["203.0.113.0/24"]
  }'
```

### Response

```json theme={null}
{
  "id": "3c7b3fd5-2563-4d81-847d-1138ed431654",
  "name": "production",
  "key": "sk-rb-kN2lOa7oIlOw-P938cWHaSZi7Z0shwtFMOl0EY089FGBBN6qPeIWL1xODJBle",
  "created_at": "2026-04-24T10:00:00Z"
}
```

<Warning>
  The full key value is returned **only once** at creation time. Copy it into a secrets manager or environment variable before the response leaves your terminal.
</Warning>

***

## Update API Key

```
PUT https://routerbase.com/api/v1/api-keys/{id}
```

### Request Body

Any subset of:

<ParamField body="name" type="string" />

<ParamField body="ip_whitelist" type="string[]" />

<ParamField body="rate_limit_rpm" type="number" />

<ParamField body="rate_limit_tph" type="number" />

<ParamField body="rate_limit_tpd" type="number" />

<ParamField body="disabled" type="boolean">
  Pause the key without losing history. `true` rejects auth; `false` re-enables.
</ParamField>

<ParamField body="credit_limit" type="number">
  Set the USD spend cap. Send a number to set, omit to leave unchanged.
</ParamField>

<ParamField body="credit_reset_interval" type="string">
  `none` | `daily` | `weekly` | `monthly`. Omit to leave unchanged.
</ParamField>

<ParamField body="expires_at" type="string (ISO 8601) | null" />

### Example

```bash theme={null}
# Pause a key without deleting it
curl -X PUT https://routerbase.com/api/v1/api-keys/{id} \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'
```

### Response

The full masked key record (same shape as a List item).

***

## Delete API Key

```
DELETE https://routerbase.com/api/v1/api-keys/{id}
```

Immediately revokes the key. Any in-flight requests using it will fail with 401 before the next upstream call. Rate-limit state in Redis is cleared as part of the delete.

Returns `204 No Content`.

***

## Errors

| Status  | When                                                                                |
| ------- | ----------------------------------------------------------------------------------- |
| **401** | No `Authorization` header, or invalid / expired JWT.                                |
| **401** | Token is an API Key — JWT is required here. Mint keys on the dashboard.             |
| **402** | (On `/v1/*` calls) the key has exhausted its `credit_limit` for the current period. |
| **403** | Key exists but is `disabled` or past `expires_at`.                                  |
| **404** | The `{id}` path doesn't resolve to a key owned by this account.                     |
| **422** | `ip_whitelist` has >10 entries, or `rate_limit_*` is negative, or `name` is empty.  |

Rate-limit enforcement on `/v1/*` calls returns **429** with `Retry-After` on violation. See [Rate Limits](/essentials/rate-limits).