Skip to main content
POST
Rotate an API key

Authorizations

Authorization
string
header
required

Short-lived JWT issued by the CarHub auth service (Better Auth), verified against its JWKS. Claims: sub (user), org_id (active organisation) and role (owner | admin | member | billing_manager). Used by the dashboard for /mgmt/v1/… only — it is never accepted on /v1/….

Path Parameters

id
string
required

API key identifier (not the secret).

Pattern: ^key_[1-9A-HJ-NP-Za-km-z]{8,32}$

Body

application/json
grace_hours
integer
default:24

How many hours the previous secret keeps working. 0 expires it immediately.

Required range: 0 <= x <= 72

Response

Key rotated. Store the new secret now.

An organisation API key. The secret is never returned after creation.

is_staging
boolean
default:false
required

Staging classification. Requires live mode and uses the organisation's shared live credits.

id
string
required
Example:

"key_9TbR3xLm"

object
string
required
Allowed value: "api_key"
name
string
required
Example:

"Production — vehicle worker"

prefix
string
required

Readable head of the key, enough to identify it in your logs.

Example:

"chk_live_a1b2"

livemode
boolean
required
scopes
string[]
required

Normalized scopes. Empty grants no business access. Wildcard grants no SDK permission. SDK write implies SDK read; storage write implies storage read.

created
integer<int64>
required

Epoch seconds, UTC.

Example:

1755300000

last_used_at
integer<int64> | null
required

Epoch seconds, UTC.

Example:

1755300000

revoked_at
integer<int64> | null
required

Epoch seconds, UTC.

Example:

1755300000

secret
string
required

The full key. Shown once, stored hashed, unrecoverable afterwards — put it in your secret manager before closing the response.

Example:

"chk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

created_by
string | null

User who created the key, kept for audit. Revoking that user does not affect the key.

Example:

"usr_5KpL2wQx"

expires_at
integer<int64> | null

Scheduled expiry, when the key was minted with one. Null for a perpetual key.

Example:

1755300000

rotates_at
integer<int64> | null

End of the grace period of a rotated key: after this instant the previous secret stops working. Null when the key was never rotated.

Example:

1755300000