Enterprise API Keys

Enterprise API keys (chb_sk_*) provide account-scoped bearer authentication for service-to-service integrations and automated pipelines.

Base path: /api/v1/accounts/{accountId}/api-keys

Authentication: JWT Bearer token (owner or admin role required)

---

List API Keys

GET /accounts/{accountId}/api-keys

Returns all API keys for the account. The raw key value is never returned in list responses.

Request

Path Parameter	Description
accountId	Account UUID

No query or body parameters.

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Production Pipeline Key",
      "keyPrefix": "chb_sk_xxxx",
      "lastFour": "abcd",
      "scopes": ["contexts:read", "agents:execute"],
      "status": "active",
      "workspaceId": null,
      "expiresAt": "2026-07-12T10:00:00.000Z",
      "lastUsedAt": "2026-04-10T14:22:00.000Z",
      "createdAt": "2026-04-13T10:00:00.000Z"
    }
  ]
}

Code Example

cURL

curl "https://api.chainabit.com/api/v1/accounts/$ACCOUNT_ID/api-keys" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(
  `${BASE_URL}/accounts/${accountId}/api-keys`,
  { headers: { Authorization: `Bearer ${TOKEN}` } }
);
const { data } = await response.json();

Python

import httpx
result = httpx.get(
    f"{BASE_URL}/accounts/{account_id}/api-keys",
    headers={"Authorization": f"Bearer {token}"},
).json()

---

Create API Key

POST /accounts/{accountId}/api-keys

Creates a new API key. The raw key value is only present in this response — it cannot be retrieved later. Store it immediately.

Request

Path Parameter	Description
accountId	Account UUID

Request body:

Field	Type	Required	Description
name	string	Yes	Human-readable label (max 120 chars)
scopes	string[]	Yes	Permission scopes (see below)
workspaceId	uuid	No	Restrict key to a specific workspace
expiresInDays	integer	No	Days until expiry (1–365); omit for no expiry

Available scopes:

Scope	Access granted
contexts:read	Read knowledge contexts, semantic search
contexts:write	Create and update knowledge contexts
agents:read	Read agent definitions and instances
agents:execute	Execute agent tools and sessions
analytics:read	Read analytics and audit data
members:read	Read account and workspace members

Response

{
  "data": {
    "id": "uuid",
    "name": "Production Pipeline Key",
    "key": "chb_sk_AbCdEfGhIjKlMnOpQrStUvWxYz01234567890AbCdEfG",
    "keyPrefix": "chb_sk_AbCd",
    "lastFour": "fGhI",
    "scopes": ["contexts:read", "agents:execute"],
    "expiresAt": "2026-07-12T10:00:00.000Z",
    "createdAt": "2026-04-13T10:00:00.000Z"
  }
}

Code Example

cURL

curl -X POST "https://api.chainabit.com/api/v1/accounts/$ACCOUNT_ID/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Pipeline Key",
    "scopes": ["contexts:read", "agents:execute"],
    "expiresInDays": 90
  }'

JavaScript

const response = await fetch(
  `${BASE_URL}/accounts/${accountId}/api-keys`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Production Pipeline Key',
      scopes: ['contexts:read', 'agents:execute'],
      expiresInDays: 90,
    }),
  }
);
const { data } = await response.json();
// data.key is the raw key — store it now

Python

import httpx
result = httpx.post(
    f"{BASE_URL}/accounts/{account_id}/api-keys",
    json={
        "name": "Production Pipeline Key",
        "scopes": ["contexts:read", "agents:execute"],
        "expiresInDays": 90,
    },
    headers={"Authorization": f"Bearer {token}"},
).json()
# result['data']['key'] — store this immediately

---

Revoke API Key

DELETE /accounts/{accountId}/api-keys/{id}

Immediately revokes the key. Revoked keys return 401 on any subsequent request.

Request

Path Parameter	Description
accountId	Account UUID
id	API key UUID

Response

{ "data": { "revoked": true, "id": "uuid" } }

Code Example

cURL

curl -X DELETE "https://api.chainabit.com/api/v1/accounts/$ACCOUNT_ID/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

await fetch(
  `${BASE_URL}/accounts/${accountId}/api-keys/${keyId}`,
  { method: 'DELETE', headers: { Authorization: `Bearer ${TOKEN}` } }
);

Python

httpx.delete(
    f"{BASE_URL}/accounts/{account_id}/api-keys/{key_id}",
    headers={"Authorization": f"Bearer {token}"},
)

---

Using an API Key

Once created, use the raw key directly as a bearer token on supported endpoints:

Authorization: Bearer chb_sk_<your-key>

API keys do not expire the session — each request independently validates the key against the stored hash.

---

Errors

Status	Code	Description
400	BAD_REQUEST	Workspace not found in this account
403	FORBIDDEN	Caller is not an account owner or admin
404	NOT_FOUND	Key not found or already revoked