---
title: "Create External Key"
method: POST
path: "/api/v1/external-keys"
tags: ["external-keys"]
---

# Create External Key

`POST /api/v1/external-keys`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/external-keys`
- Auth: none declared

Create a new external API key for the current workspace.

Issue #381: owner-only (router-level dependency).
Issue #385: workspace-scoped — the new key is stored with the caller's
current_workspace_id and context_id=None. Per-workspace uniqueness is
enforced by (a) the app-layer pre-checks in this handler and (b) the
partial unique index on (workspace_id, context_id, provider) WHERE enabled=true (NULLS NOT DISTINCT).

## Headers

- `authorization` string, nullable

## Request body

- ExternalKeyCreate: Create external API key request.
  - `key_name` string, required
  - `provider` string, required
  - `value` string, required
  - `enabled` boolean

## Response `200`

Successful Response

- ExternalKeyResponse: External API key response (masked). No ``id``: external keys are addressed by ``key_name`` (#1008 dropped the integer primary key from the response).
  - `key_name` string, required
  - `provider` string, required
  - `masked_value` string, required
  - `user_id` string, required
  - `enabled` boolean, required
  - `is_protected` boolean, required
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)