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). Used by the dashboard for /mgmt/v1/… only — it is never accepted on /v1/….

Headers

Idempotency-Key
string

Client-generated key (a UUID is ideal) making this POST safe to retry. The first request is executed and its response stored for 24 h; any replay with the same key returns that stored response with Idempotent-Replayed: true and bills nothing. Reusing a key with a different payload is a 409 idempotency_key_reuse.

Required string length: 8 - 255

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_seconds
integer
default:3600

How long the previous secret keeps working. 0 revokes it immediately.

Required range: 0 <= x <= 604800

Response

Key rotated. Store the new secret now.

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

id
string
required
Example:

"key_9TbR3xLm"

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

"Production — inspection worker"

prefix
string
required

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

Example:

"chk_live_a1b2"

livemode
boolean
required
scopes
enum<string>[]
required

Endpoint families the key may call. Empty means every family.

Available options:
vehicle,
vin,
plate,
document,
dashboard,
engine,
video,
damage,
tire,
parts,
pricing,
render,
viewer,
inspections
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