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

# API Keys

> Manage API keys for the BlindCast Server — scopes, bootstrap key, creation, listing, and revocation.

The BlindCast Server uses API keys to authenticate management requests. Keys are SHA-256 hashed before storage — the raw key is only shown once at creation time.

## Scopes

| Scope      | Permissions                                      |
| ---------- | ------------------------------------------------ |
| `admin`    | Manage API keys, manage content, presign uploads |
| `full`     | Manage content, presign uploads, manage API keys |
| `upload`   | Presign uploads                                  |
| `playback` | Read content only                                |

Only `admin` and `full` scopes can create, list, or revoke API keys.

## Bootstrap API key

For automated deployments, set the `ADMIN_API_KEY` environment variable:

```bash theme={null}
ADMIN_API_KEY=bk_your_bootstrap_key
```

This key is accepted as an `admin`-scope key without being stored in the database. It lets you make the first API call to create a proper stored key.

## First-launch setup

If no API keys exist and `ADMIN_API_KEY` is not set, use the setup endpoint:

```bash theme={null}
curl -X POST http://localhost:4100/api/v1/setup \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin Key"}'
```

**Response (201):**

```json theme={null}
{
  "api_key": { "id": "...", "name": "Admin Key", "scope": "admin", "..." : "..." },
  "raw_key": "bk_a1b2c3d4..."
}
```

<Warning>
  The setup endpoint only works once — it returns `409` if any API keys already exist. Store the `raw_key` immediately; it cannot be retrieved again.
</Warning>

The admin dashboard at `/admin` guides you through this process with a setup wizard.

## Create an API key

```http theme={null}
POST /api/v1/api-keys
Authorization: Bearer bk_your_admin_key
```

```json theme={null}
{
  "name": "Upload Service",
  "scope": "upload",
  "expiresAt": "2026-12-31T00:00:00Z"
}
```

| Field       | Type   | Required | Description                                                |
| ----------- | ------ | -------- | ---------------------------------------------------------- |
| `name`      | string | Yes      | Display name                                               |
| `scope`     | string | No       | `admin`, `full`, `upload`, or `playback` (default: `full`) |
| `expiresAt` | string | No       | ISO 8601 expiry date                                       |

**Response (201):**

```json theme={null}
{
  "api_key": {
    "id": "uuid-...",
    "name": "Upload Service",
    "keyPrefix": "bk_a1b2...",
    "scope": "upload",
    "expiresAt": "2026-12-31T00:00:00.000Z",
    "revokedAt": null,
    "createdAt": "2026-03-02T12:00:00.000Z"
  },
  "raw_key": "bk_a1b2c3d4e5f6..."
}
```

<Warning>
  Save the `raw_key` — it is only returned once. The stored `keyPrefix` shows the first few characters for identification.
</Warning>

## List API keys

```http theme={null}
GET /api/v1/api-keys
Authorization: Bearer bk_your_admin_key
```

**Response (200):**

```json theme={null}
{
  "api_keys": [
    {
      "id": "uuid-...",
      "name": "Upload Service",
      "keyPrefix": "bk_a1b2...",
      "scope": "upload",
      "lastUsedAt": "2026-03-02T12:00:00.000Z",
      "expiresAt": "2026-12-31T00:00:00.000Z",
      "revokedAt": null,
      "createdAt": "2026-03-02T12:00:00.000Z"
    }
  ]
}
```

Raw keys are never returned — only the prefix is shown.

## Revoke an API key

```http theme={null}
DELETE /api/v1/api-keys/:id
Authorization: Bearer bk_your_admin_key
```

**Response (200):** The revoked key object with a `revokedAt` timestamp.

Revoked keys are rejected on all subsequent requests.

## Key format

API keys use the format `bk_` followed by 64 hex characters (32 random bytes):

```
bk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
```

The `bk_` prefix makes keys easy to identify in logs and configuration.

## Next steps

* [Content API](/server/content-api) — register and manage content
* [Admin Dashboard](/server/admin-dashboard) — manage keys from the browser
* [Docker Setup](/server/docker) — environment variables and deployment