Skip to main content
POST
Create 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/….

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

Body

application/json
name
string
required
Required string length: 1 - 128
is_staging
boolean
default:false

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

livemode
boolean
default:true

false mints a chk_test_ key. With live mode, is_staging=true mints a chk_stg_ key.

scopes
string[]

Explicit permissions from /mgmt/v1/api-key-scopes. Missing or empty means no business access. Unknown values are rejected and duplicates normalized.

Response

Key created. Store 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