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

# Create a new API key

`POST /api/keys`

## Request

- Base URL: `https://www.audioscrape.com`
- URL: `https://www.audioscrape.com/api/keys`
- Auth: HTTP bearer

Generates a new workspace-scoped API key. The full `key_value` is returned **only** in this response — Audioscrape stores a SHA-256 hash and the prefix only, so save the raw key immediately on the client side. If you lose it, rotate the key.

Accepts either a session cookie or an existing API key as auth.

## Request body

- CreateApiKey
  - `expires_at` string, date-time, nullable: Optional: when this key stops working (RFC 3339). Omit for a key that never expires — the behaviour of every key issued before 2026-07-31.
  - `key_name` string, required: Human-readable label for the key. Stored verbatim; visible in the dashboard and in `last_used` audit logs. Recommended: identify the integration + environment, e.g. `"acme-dev-connector-v1"`.
  - `workspace_id` integer, nullable: Optional: scope this key to a single workspace. If omitted, the key uses the user's current_workspace_id at each request (legacy behavior). To scope to a workspace, the caller must be a member of it.

## Response `201`

Key created. `key_value` is shown in full here for the only time.

- ApiKey
  - `created_at` string, nullable: RFC 3339 UTC timestamp.
  - `expires_at` string, nullable: When the key stops authenticating (RFC 3339). `null` = never expires, which is the case for every key issued before 2026-07-31.
  - `id` integer, required
  - `key_name` string, required: Human-readable label for the key (shown in the dashboard).
  - `key_prefix` string, required: Display-safe prefix of the key (first 12 characters + "..."). Always present. Use this to identify the key in logs and UIs.
  - `key_value` string, nullable: The full bearer token, format `sk_<base64(32 random bytes)>`. **Returned only in the response to `POST /api/keys`** — Audioscrape stores only a SHA-256 hash, so list / delete endpoints cannot recover the raw value. Save it client-side immediately on creation.
  - `last_used` string, nullable: RFC 3339 UTC timestamp of the most recent request that used this key. `null` if the key has never been used.
  - `last_used_ip` string, nullable: Source IP of the request described by `last_used` (as seen by our edge). `null` if the key has never been used or the IP was unavailable. Use it to spot a leaked key being used from somewhere unexpected.
  - `workspace_id` integer, nullable: Workspace this key is scoped to. `null` means the key follows the user's `current_workspace_id` at request time (legacy behavior).

## Other responses

- `401`: Missing or invalid session / key

---

[API](https://skmtc.dev/audioscrape/apis/audioscrape-rest-api.md) · [All operations](https://skmtc.dev/audioscrape/apis/audioscrape-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/audioscrape/apis/audioscrape-rest-api/revisions/29b5788227cf?raw)