Rotate an API key
Issues a new secret for the same logical key and schedules the old one for expiry after
grace_seconds (0 = immediate), so a fleet can be redeployed without a gap. The new
secret is shown once. Minimum role: admin.
Authorizations
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
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.
8 - 255Path Parameters
API key identifier (not the secret).
^key_[1-9A-HJ-NP-Za-km-z]{8,32}$Body
How long the previous secret keeps working. 0 revokes it immediately.
0 <= x <= 604800Response
Key rotated. Store the new secret now.
An organisation API key. The secret is never returned after creation.
"key_9TbR3xLm"
"api_key""Production — inspection worker"
Readable head of the key, enough to identify it in your logs.
"chk_live_a1b2"
Endpoint families the key may call. Empty means every family.
vehicle, vin, plate, document, dashboard, engine, video, damage, tire, parts, pricing, render, viewer, inspections Epoch seconds, UTC.
1755300000
Epoch seconds, UTC.
1755300000
Epoch seconds, UTC.
1755300000
The full key. Shown once, stored hashed, unrecoverable afterwards — put it in your secret manager before closing the response.
"chk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
User who created the key, kept for audit. Revoking that user does not affect the key.
"usr_5KpL2wQx"
Scheduled expiry, when the key was minted with one. Null for a perpetual key.
1755300000
End of the grace period of a rotated key: after this instant the previous secret stops working. Null when the key was never rotated.
1755300000