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

# Authentication

> Bearer tokens, scoping, rotation, and Enterprise IP allowlist.

All requests authenticate via the `Authorization: Bearer <key>` header.

```bash theme={null}
curl https://api.rimp.example/v1/models \
  -H "Authorization: Bearer sk_live_..."
```

## Key formats

| Prefix      | Environment | Notes                                           |
| ----------- | ----------- | ----------------------------------------------- |
| `sk_live_…` | Production  | Real billing applies. Default tier limits.      |
| `sk_test_…` | Test mode   | Sandbox. No charges. Returns synthetic outputs. |

Keys are **shown once at creation** and stored as a SHA-256 hash. Lose it = rotate it.

## Scopes (optional)

By default a key inherits the role of the user who created it. You can narrow a key's blast radius:

| Scope              | Allows                                                 |
| ------------------ | ------------------------------------------------------ |
| `images:write`     | `POST /v1/images`, `POST /v1/comparisons` (image-only) |
| `videos:write`     | `POST /v1/videos`                                      |
| `generations:read` | `GET /v1/generations/{id}`                             |
| `webhooks:manage`  | CRUD on `/v1/webhooks`                                 |

Set scopes when creating a key via the dashboard. Empty `scopes` = full access (default).

## Rotation

```bash theme={null}
# 1. Create the new key (dashboard or API)
curl -X POST https://api.rimp.example/v1/api-keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{"name": "production-2026-q2"}'

# 2. Deploy the new key to your servers
# 3. Revoke the old one
curl -X DELETE https://api.rimp.example/v1/api-keys/key_old \
  -H "Authorization: Bearer $ADMIN_KEY"
```

Revocation is immediate. Subsequent requests with the revoked key get `401 invalid_api_key`.

## IP allowlist (Enterprise)

Restrict a key to a list of CIDR ranges:

```bash theme={null}
curl -X PATCH https://api.rimp.example/v1/api-keys/key_abc \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{"ipAllowlist": ["203.0.113.0/24", "2001:db8::/32"]}'
```

Requests outside the allowlist return `403 ip_not_allowed`.

## What happens when auth fails

| Status | Code                    | Why                                             |
| ------ | ----------------------- | ----------------------------------------------- |
| 401    | `missing_authorization` | No `Authorization` header                       |
| 401    | `invalid_authorization` | Header isn't `Bearer <token>`                   |
| 401    | `invalid_api_key`       | Key not found or revoked                        |
| 403    | `ip_not_allowed`        | Caller IP outside this key's allowlist          |
| 403    | `insufficient_role`     | Key scope doesn't cover the requested operation |