Skip to main content
POST
Create API Key

Overview

Creates a new API key for your organization. The full key secret is returned only once in the response; it cannot be retrieved again. Store it securely immediately after creation. You can assign a name for identification, specific scopes to limit access, an optional expiration date, and key-value metadata. You cannot grant scopes the calling key does not itself hold, and an organization can have at most 25 active keys. Requires the api-keys:manage scope. This endpoint requires an Idempotency-Key header; see Idempotency.

Request Body

name
string
required
Human-readable name for the key, 1-255 characters (e.g. “Production Backend”).
scopes
string[]
required
Authorized scopes (1-20 values, must be a subset of the calling key’s scopes):
expires_at
string | null
Optional ISO 8601 timestamp for key expiration. Must be in the future. Omit or pass null for a non-expiring key.
metadata
object
Optional key-value metadata (string values, max 50 keys).

Response

Returns the full API key object plus the one-time key secret, flat at the top level.
id
string
Key ID (key_*).
object
string
Always api_key.
name
string
Key name.
key
string
Full API key secret. This is the only time it is returned.
prefix
string
First 12 characters of the key, for identification.
scopes
string[]
Authorized scopes.
rate_limit_tier
string
Rate limit tier label for the key. standard by default.
status
string
Lifecycle state: active, expired, or revoked. Always active on creation.
expires_at
string | null
Expiry timestamp, or null.
last_used_at
string | null
Always null on creation.
metadata
object
Key-value metadata.
revoked_at
string | null
Always null on creation.
created_by
string
ID of the API key that created this key.
created_at
string
Creation timestamp.
updated_at
string
Last update timestamp.
request_id
string
Unique request identifier for support and debugging.

Code Examples

Errors

Retrying with the same Idempotency-Key and the same body replays the cached response, including the same key secret, so an ambiguous network failure never mints a second credential. Duplicate key names are allowed and do not 409.