---
title: "Rotate an API key"
method: POST
path: "/api/keys/{id}/rotate"
tags: ["API Keys"]
---

# Rotate an API key

`POST /api/keys/{id}/rotate`

## Request

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

Atomically replaces the key's secret (GH#485): the key keeps its id, name, workspace pin and expiry; the old secret stops authenticating the moment this call returns; the new secret is in `key_value` — shown only in this response. Prefer this over delete-and-recreate: the key's identity survives and there is no window with zero valid credentials. `last_used` resets to `null` because the new secret has never been used.

Accepts either a session cookie or an existing API key as auth. A key can rotate itself.

## Path parameters

- `id` integer, required

## Response `200`

Key rotated. `key_value` holds the NEW secret, 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
- `404`: No key with this id belongs to you

---

[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)