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

# Kataven Hub API — API keys (sk_live_)

> REST API reference for sk_live_ server-to-server credentials. Listing is open; create/update/delete require Hub UI auth.

`sk_live_` server-to-server credentials. **Listing endpoints work with any auth; CRUD operations are gated to the Hub UI** — a leaked sk\_live\_ cannot mint another. Mint via [hub.kataven.ai/settings](https://hub.kataven.ai/settings) → API Keys.

## Endpoints at a glance

| Method   | Path                                                  | Summary                                               |
| -------- | ----------------------------------------------------- | ----------------------------------------------------- |
| `GET`    | [`/api/v1/api-keys`](#get-api-v1-api-keys)            | List API keys                                         |
| `POST`   | [`/api/v1/api-keys`](#post-api-v1-api-keys)           | Create an API key (returns plaintext sk\_live\_ ONCE) |
| `PATCH`  | [`/api/v1/api-keys/{id}`](#patch-api-v1-api-keys-id)  | Update or revoke an API key                           |
| `DELETE` | [`/api/v1/api-keys/{id}`](#delete-api-v1-api-keys-id) | Delete or soft-disable an API key                     |

## Reference

### `GET /api/v1/api-keys`

List API keys

Returns metadata for every sk\_live\_ key in this account. Plaintext key values are never returned — only the last 8 characters and the row id.

**Responses**

| Code  | Description                     | Body                 |
| ----- | ------------------------------- | -------------------- |
| `200` | OK                              | `array<data.ApiKey>` |
| `400` | Missing X-Account-ID header     | `string`             |
| `401` | Missing or invalid bearer token | `string`             |
| `500` | Database error                  | `string`             |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/api-keys \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `POST /api/v1/api-keys`

Create an API key (returns plaintext sk\_live\_ ONCE)

Mints a new sk\_live\_ credential. The plaintext value is returned in the response and never again — store it in your secret manager. Requires Hub UI (Zitadel) auth; sk\_live\_ keys cannot mint other sk\_live\_ keys.

**Request body** (`application/json`)

Schema: `handlers.CreateApiKeyRequest`. Server-set fields (`id`, `created_at`, `updated_at`, …) are ignored if supplied; only the user-settable fields are shown below.

| Field    | Type     | Description          |
| -------- | -------- | -------------------- |
| `expiry` | `string` | e.g. `90d`           |
| `name`   | `string` | e.g. `ci-deploy-bot` |

**Responses**

| Code  | Description                     | Body                             |
| ----- | ------------------------------- | -------------------------------- |
| `201` | Created                         | [`data.CreatedApiKey`](#schemas) |
| `400` | Invalid body or name required   | `string`                         |
| `401` | Missing or invalid bearer token | `string`                         |
| `403` | Requires Hub UI auth            | `string`                         |
| `500` | Database error                  | `string`                         |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/api-keys \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "expiry": "90d",
    "name": "ci-deploy-bot"
  }'
  ```
</CodeGroup>

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

Update or revoke an API key

Renames the key or revokes it (disabled=true sets disabled\_at=now() — idempotent). Requires Hub UI (Zitadel) auth so a leaked sk\_live\_ cannot disable other keys.

**Parameters**

| Name | In   | Type     | Required | Description       |
| ---- | ---- | -------- | -------- | ----------------- |
| `id` | path | `string` | Yes      | API key id (uuid) |

**Request body** (`application/json`)

Schema: `handlers.UpdateApiKeyRequest`. Server-set fields (`id`, `created_at`, `updated_at`, …) are ignored if supplied; only the user-settable fields are shown below.

| Field      | Type      | Description                  |
| ---------- | --------- | ---------------------------- |
| `disabled` | `boolean` | e.g. `False`                 |
| `name`     | `string`  | e.g. `ci-deploy-bot-renamed` |

**Responses**

| Code  | Description          | Body     |
| ----- | -------------------- | -------- |
| `204` | Updated              | —        |
| `400` | Invalid body         | `string` |
| `403` | Requires Hub UI auth | `string` |
| `500` | Database error       | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/api-keys/agent_01HZ2N... \
    -X PATCH \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "disabled": false,
    "name": "ci-deploy-bot-renamed"
  }'
  ```
</CodeGroup>

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

Delete or soft-disable an API key

Hard-deletes the row if the key was never used; otherwise sets disabled\_at=now() to preserve the audit trail. Requires Hub UI auth.

**Parameters**

| Name | In   | Type     | Required | Description       |
| ---- | ---- | -------- | -------- | ----------------- |
| `id` | path | `string` | Yes      | API key id (uuid) |

**Responses**

| Code  | Description          | Body     |
| ----- | -------------------- | -------- |
| `204` | Deleted              | —        |
| `403` | Requires Hub UI auth | `string` |
| `500` | Database error       | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/api-keys/agent_01HZ2N... \
    -X DELETE \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>