# API Keys

> Create, list, update, and revoke API keys through the dashboard API.

API keys authenticate programmatic access. Each key can be scoped to specific operations and revoked independently. Keys are managed through the dashboard API, which is authenticated with your browser session (JWT) — not with an API key.

> [!NOTE]
> The full key (pxsk_ followed by 32 hex characters) is returned only once, at creation. Store it immediately in a secret manager or environment variable.

## `POST /api/keys`

Create a new API key. The raw key is returned once, in this response only.

**Auth:** Dashboard (JWT)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Human-friendly name, 1 to 100 characters. |
| `scopes` | `string[]` | No | Allowed operations. Defaults to images:generate, images:edit, videos:generate, uploads:write. |
| `expires_in_days` | `number` | No | Days until expiry, 1 to 365. Null means the key never expires. |

**Response**

```json
{
  "id": "9b1c7e0a-...",
  "name": "Production server",
  "raw_key": "pxsk_1a2b3c...   (shown only once)",
  "key_prefix": "pxsk_1a2b",
  "scopes": ["images:generate", "images:edit", "videos:generate", "uploads:write"],
  "created_at": "2026-06-17T20:00:00Z"
}
```

## `GET /api/keys`

List your API keys. Values are masked — only the prefix is shown.

**Auth:** Dashboard (JWT)

## `GET /api/keys/{id}`

Get a single API key by id.

**Auth:** Dashboard (JWT)

## `PATCH /api/keys/{id}`

Update a key’s name, scopes, or active status.

**Auth:** Dashboard (JWT)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | No | New name, 1 to 100 characters. |
| `scopes` | `string[]` | No | New scope set. |
| `is_active` | `boolean` | No | Activate or deactivate the key. |

## `DELETE /api/keys/{id}`

Revoke a key. It stops working immediately and returns 204 No Content. This cannot be undone.

**Auth:** Dashboard (JWT)

## Available scopes

```
images:generate   Generate images from text prompts
images:edit       Edit existing images with instructions
videos:generate   Generate videos from text or images
uploads:write     Upload files to managed assets for image/video inputs
audio:generate    Generate audio and music
agent:run         Run AI agent workflows
```

> [!WARNING]
> Best practices: use separate keys per environment (dev/staging/prod), grant only the scopes each key needs, rotate keys periodically, and never commit them to source control.