Skip to main content
POST
Rotate an API key

Authorizations

Authorization
string
header
required

A Barndoor API key, sent as Authorization: Bearer <key>. Keys are prefixed bdai_ and are opaque — do not attempt to decode one. Interchangeable with an OAuth 2.0 access token.

Path Parameters

id
string<uuid>
required

Identifier, a UUID

Body

application/json

Body of POST /admin/api-keys/{id}/rotate and POST /user/api-keys/{id}/rotate (BCP-5195). An empty object rotates immediately and keeps the key's expiry.

expires_at
string<date-time> | null

New expiry for the key. Omit to keep the current one; null removes the expiry. Must be in the future.

grace_period_secs
integer<int32>

How long the previous secret keeps authenticating after rotation, in seconds. 0 (the default) cuts it off immediately. At most 7 days.

Required range: x >= 0

Response

The rotated key, including its new secret

id
string<uuid>
required

Unchanged by rotation.

key
string
required

The new API key — only returned by this call, never stored.

key_prefix
string
required
name
string
required
expires_at
string<date-time> | null
previous_key_expires_at
string<date-time> | null

Until when the previous secret still authenticates; None when it was cut off immediately.

rotated_at
string<date-time> | null