Create API Key
API Keys
Create API Key
Generate a new API key for the organization
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 theapi-keys:manage scope. This endpoint requires an Idempotency-Key header; see Idempotency.
Request Body
Human-readable name for the key, 1-255 characters (e.g. “Production Backend”).
Authorized scopes (1-20 values, must be a subset of the calling key’s scopes):
Optional ISO 8601 timestamp for key expiration. Must be in the future. Omit or pass
null for a non-expiring key.Optional key-value metadata (string values, max 50 keys).
Response
Returns the full API key object plus the one-timekey secret, flat at the top level.
Key ID (
key_*).Always
api_key.Key name.
Full API key secret. This is the only time it is returned.
First 12 characters of the key, for identification.
Authorized scopes.
Rate limit tier label for the key.
standard by default.Lifecycle state:
active, expired, or revoked. Always active on creation.Expiry timestamp, or
null.Always
null on creation.Key-value metadata.
Always
null on creation.ID of the API key that created this key.
Creation timestamp.
Last update timestamp.
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.Related Endpoints
- List API Keys, view all keys
- Rotate API Key, rotate an existing key
- Get Current Organization, organization profile