Create an API key | Respan Docs

Create a new API key.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects an object.

namestringOptional

Key name.

expiry_datedatetimeOptional

Expiry date (ISO 8601).

max_usageintegerOptionalDefaults to -1

Max usage count. -1 = unlimited.

rate_limitintegerOptional

Calls per minute. Overridden by plan limit.

spending_limitdoubleOptional

Spending limit in USD for gateway usage.

is_testbooleanOptionalDefaults to false

Test key (true) or production key (false).

limit_policieslist of objectsOptional

Optional. Spending, token, or request caps to create and scope to this key in the same call. The response echoes the created policies in full (each with its id, meter_definition_id, and current_state). Caps are stored and visible as soon as they are created, but the gateway enforces them only where the limit system is enabled for your environment. Where it is not enabled, a cap records no usage and never blocks.

Optional. Spending, token, or request caps to create and scope to this key in the same call. The response echoes the created policies in full (each with its `id`, `meter_definition_id`, and `current_state`). Caps are stored and visible as soon as they are created, but the gateway enforces them only where the limit system is enabled for your environment. Where it is not enabled, a cap records no usage and never blocks.

Response

Created API key.

idstringOptional

API key ID.

namestringOptional

Key name.

prefixstringOptional

Key prefix.

is_testbooleanOptional

Test or production key.

expiry_datedatetimeOptional

Expiry date.

max_usageintegerOptional

Max usage count. -1 = unlimited.

rate_limitdouble or nullOptional

Requests per minute. null uses the organization default.

spending_limitdoubleOptional

Spending limit in USD.

api_keystringOptional

The API key value. Only returned on creation - store it securely.

key_usageintegerOptional

Number of times this key has been used.

createddatetimeOptional

When the API key was created.

unique_organization_idstring or nullOptional

Owning organization UUID.

Errors

401

Unauthorized Error