---
title: "Create API key"
method: POST
path: "/api/v1/api-keys"
tags: ["api-keys"]
---

# Create API key

`POST /api/v1/api-keys`

Create a new API key.

Returns the full API key exactly once. The key cannot be retrieved
after this response - only the masked key_prefix is stored.

Scopes are validated against the creating user's permissions.
You cannot grant scopes you don't have.

RLS: Filtered to current client (ClientRLSDB).

Raises:
    ApiKeyScopeExceededError: If requested scopes exceed user's permissions (403)

## Request body

- CreateApiKeyRequest — Request model for creating an API key.
  - `description` string, nullable — Optional description
  - `expires_at` string, date-time, nullable — Optional expiration datetime (UTC)
  - `name` string, required — Name for the API key
  - `scopes` string[], required — List of scopes to grant to this key

## Response `201`

Successful Response

- CreateApiKeyResponse — Response model for created API key (includes full key once).
  - `created_at` string, date-time, required — Creation timestamp
  - `expires_at` string, date-time, nullable, required — Expiration datetime
  - `id` string, uuid, required — API key UUID
  - `key` string, required — Full API key (only shown once)
  - `name` string, required — API key name
  - `scopes` string[], required — Granted scopes

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `422` — Validation Error

## Changes

- **2026-01-29** `5f4f08ff6556` — 1 warning, 4 info
  - removed the optional property `detail` from the response with the `422` status
  - added the optional property `errors` to the response with the `422` status
  - added the required property `code` to the response with the `422` status
  - added the required property `message` to the response with the `422` status
  - …1 more

[Change history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/api-keys/post.md)

---

[API](https://skmtc.dev/kater-ai/apis/kater-api.md) · [All operations](https://skmtc.dev/kater-ai/apis/kater-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kater-ai/kater-api/revisions/d2a2a2d0775e/schema)