Sign in
API Keys

Create a new API key

Create a new API key for the authenticated user. The plaintext key is returned only in this response. Treat it as a write-only, sensitive value; it cannot be retrieved later. Authenticate with a management key, or with a Connect client secret. external_user and external_api_key are accepted only with a client secret, and external_user is required there; supplying either field with a management key is rejected with 403.

post/keys

Request body

creator_user_idstring nullable

Optional user ID of the key creator. Only meaningful for organization-owned keys where a specific member is creating the key.

expires_atstring date-time nullable

Optional ISO 8601 UTC timestamp when the API key should expire. Must be UTC, other timezones will be rejected

external_api_keystring

Optional partner-supplied API key. Stored as a SHA-256 hash and never returned. Accepted only when authenticating with a Connect client secret; supplying it with a management key is rejected with 403.

external_userstring

Partner's end-user identifier for attribution, between 1 and 512 characters. Accepted only when authenticating with a Connect client secret, where it is required; supplying it with a management key is rejected with 403.

include_byok_in_limitboolean

Whether to include BYOK usage in the limit

limitnumber double nullable

Optional spending limit for the API key in USD

limit_reset'daily' | 'weekly' | 'monthly' | 'null' nullable

Type of limit reset for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday.

namestring required

Name for the new API key

workspace_idstring uuid

The workspace to create the API key in. Defaults to the default workspace if not provided.

Example request

{
  "expires_at": "2027-12-31T23:59:59Z",
  "include_byok_in_limit": true,
  "limit": 50,
  "limit_reset": "monthly",
  "name": "My New API Key"
}

Response

API key created successfully

keystring required

The actual API key string (only shown once)

Example response

{
  "data": {
    "byok_usage": 0,
    "byok_usage_daily": 0,
    "byok_usage_monthly": 0,
    "byok_usage_weekly": 0,
    "created_at": "2025-08-24T10:30:00Z",
    "creator_user_id": "user_2dHFtVWx2n56w6HkM0000000000",
    "disabled": false,
    "expires_at": "2027-12-31T23:59:59Z",
    "external_user": null,
    "hash": "f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943",
    "include_byok_in_limit": true,
    "label": "My New API Key",
    "limit": 50,
    "limit_remaining": 50,
    "limit_reset": "monthly",
    "name": "My New API Key",
    "updated_at": null,
    "usage": 0,
    "usage_daily": 0,
    "usage_monthly": 0,
    "usage_weekly": 0,
    "workspace_id": "0df9e665-d932-5740-b2c7-b52af166bc11"
  },
  "key": "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"
}

Changes