API keys

Create, list, and revoke your organization's API keys.

Manage the keys your backend uses to call the API. For key format, modes, scopes, rotation, and security, see Authentication.

Create a key

POST /v1/api-keys — Scope: organization:write

Mints a new key. The full secret is returned once, in this response — store it immediately. Live keys require a verified business: requesting mode: "live" for an unverified organization returns 403 kyb_required. Test keys are always allowed.

Body parameters

Field	Type	Required	Description
`mode`	string	Yes	`test` or `live`.
`name`	string	No	An optional label to identify the key.
`scopes`	string[]	No	The scopes to grant. If omitted, the key gets the full default scope set. Valid scopes: `payouts:write`, `payouts:read`, `balances:read`, `webhooks:write`, `webhooks:read`, `organization:read`, `organization:write`.

Request

bash

curl https://api.caiboglobal.com/v1/api-keys \
  -H "X-API-Key: $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "live",
    "name": "Production server",
    "scopes": ["payouts:write", "payouts:read", "balances:read"]
  }'

Response — 201 Created

json

{
  "id": "key_7a8b9c0d",
  "object": "api_key",
  "prefix": "ck_live_a1b2",
  "mode": "live",
  "name": "Production server",
  "scopes": ["payouts:write", "payouts:read", "balances:read"],
  "key": "ck_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "created_at": "2026-07-23T14:03:00Z"
}

key is the full secret and appears only here. Store it in your secret manager now — you can't retrieve it later. Listing keys returns only the prefix.

Errors

HTTP	type	code	When
400	invalid_request_error	bad_request	An invalid `mode` or malformed body.
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `organization:write`.
403	compliance_error	kyb_required	`mode: "live"` for an unverified organization.
429	rate_limit_error	rate_limited	Too many requests.

List keys

GET /v1/api-keys — Scope: organization:read

Returns your organization's keys as metadata only — never the secret.

bash

curl https://api.caiboglobal.com/v1/api-keys \
  -H "X-API-Key: $CAIBO_API_KEY"

Response — 200 OK

json

{
  "object": "list",
  "data": [
    {
      "id": "key_7a8b9c0d",
      "object": "api_key",
      "prefix": "ck_live_a1b2",
      "mode": "live",
      "name": "Production server",
      "scopes": ["payouts:write", "payouts:read", "balances:read"],
      "revoked": false,
      "created_at": "2026-07-23T14:03:00Z",
      "last_used_at": "2026-07-23T15:20:11Z"
    }
  ]
}

Errors

HTTP	type	code	When
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `organization:read`.
429	rate_limit_error	rate_limited	Too many requests.

Revoke a key

DELETE /v1/api-keys/{id} — Scope: organization:write

Revokes a key. It is rejected on its very next request. Revocation is immediate and can't be undone. Returns 204 No Content.

bash

curl -X DELETE https://api.caiboglobal.com/v1/api-keys/key_7a8b9c0d \
  -H "X-API-Key: $CAIBO_API_KEY"

Errors

HTTP	type	code	When
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `organization:write`.
404	invalid_request_error	not_found	No such key, or it's already revoked.
429	rate_limit_error	rate_limited	Too many requests.