---
title: API Keys API
path: reference/api/api-keys
status: published
---

# API Keys API

Reference for the `API Keys` endpoint group — 3 endpoints.

Generated from the live OpenAPI spec. Re-run `_generate_api_reference.py` after backend changes.

## Authentication

All endpoints require a Bearer JWT in the `Authorization` header unless noted otherwise. See [Concepts → Tokens and scopes](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/reference/oauth-endpoints) for how to obtain one.

## Endpoints

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

_List Api Keys_

List API keys — your own by default; all keys for super_admins.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `all_users` | query | no | `boolean` | super_admin only: list every user's keys, not just your own. |
| `include_revoked` | query | no | `boolean` |  |
| `authorization` | header | no | `string` \| `null` |  |
| `x-api-key` | header | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → object |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

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

_Create Api Key_

Create a personal API key for the calling admin.

The plaintext secret is returned exactly once, in this response.
Only a hash is stored — a lost secret means revoke + re-create.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `authorization` | header | no | `string` \| `null` |  |
| `x-api-key` | header | no | `string` \| `null` |  |

**Request body:**

Required.

- `application/json` → [`CreateApiKeyRequest`](#schema-createapikeyrequest)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → object |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/admin/api-keys/{key_id}`

_Revoke Api Key_

Revoke an API key. Owners revoke their own; super_admins any.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `key_id` | path | yes | `string` |  |
| `authorization` | header | no | `string` \| `null` |  |
| `x-api-key` | header | no | `string` \| `null` |  |

**Request body:**

- `application/json` → [`RevokeApiKeyRequest`](#schema-revokeapikeyrequest) \| `null`

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → object |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## Schemas

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

### `CreateApiKeyRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `scopes` | array of `string` | yes | Subset of {admin:read, admin:write}. Write implies read. |
| `expires_in_days` | `integer` \| `null` | no | Optional expiry. Omit for a non-expiring key. |
| `group_id` | `string` \| `null` | no | Optional group binding: the key only works while you remain an active member of this group. |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `RevokeApiKeyRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | `string` \| `null` | no |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |