API Keys

Rotate an API key

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.

post/api/keys/{id}/rotate

Request

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

Path parameters

idinteger required

API key ID (from the id field on create / list)

Response

Key rotated. key_value holds the NEW secret, shown in full here for the only time.

created_atstring nullable

RFC 3339 UTC timestamp.

expires_atstring nullable

When the key stops authenticating (RFC 3339). null = never expires, which is the case for every key issued before 2026-07-31.

idinteger required
key_namestring required

Human-readable label for the key (shown in the dashboard).

key_prefixstring required

Display-safe prefix of the key (first 12 characters + "..."). Always present. Use this to identify the key in logs and UIs.

key_valuestring 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_usedstring nullable

RFC 3339 UTC timestamp of the most recent request that used this key. null if the key has never been used.

last_used_ipstring 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_idinteger nullable

Workspace this key is scoped to. null means the key follows the user's current_workspace_id at request time (legacy behavior).

Example response

{
  "created_at": "2026-05-16T08:30:00Z",
  "key_name": "acme-dev-connector-v1",
  "key_prefix": "sk_abc123def...",
  "key_value": "sk_abc123base64encodedrandombytes...",
  "last_used": "2026-05-16T08:30:00Z",
  "last_used_ip": "203.0.113.7",
  "workspace_id": 42
}

Changes

No recorded changes to this operation across all 1 revision of this API.