Authentication

All API requests require an API key passed via the X-API-Key header.

API Key Format

Keys follow the format kolbo_live_<60 hex characters> — the literal prefix kolbo_live_ plus 30 random bytes rendered as hex.

Creating a Key

Via Dashboard (Recommended)

Go to Developer Console and click Create Key.

Via API

The key-management endpoints live under /api/api-keys (not /api/v1). Creating, revealing and revoking a key require an interactive sign-in: the request must be authenticated with a JWT from your browser session (Authorization: Bearer ...), which is what the Developer Console sends.

curl -X POST https://api.kolbo.ai/api/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration", "permissions": ["read", "write"], "expiresInDays": 365}'

Request Body

Returns 201 on success:

{
  "status": true,
  "data": {
    "id": "key_id",
    "keyPrefix": "kolbo_live_a1b2c3d4e...",
    "name": "My Integration",
    "permissions": ["read", "write"],
    "createdAt": "2026-03-05T10:00:00Z",
    "expiresAt": "2027-03-05T10:00:00Z"
  },
  "fullKey": "kolbo_live_abc123def456...",
  "message": "API key created. You can view the full key again any time from this page."
}

Reveal a Key Again

curl https://api.kolbo.ai/api/api-keys/KEY_ID/reveal \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns { "status": true, "fullKey": "kolbo_live_..." }. Ownership is enforced in the lookup, so a key belonging to someone else is indistinguishable from one that does not exist (404, API key not found).

Every other failure returns 400 with a message:

Revealing a key does not require it to be active — revoked and expired keys can still be revealed, but they will not authenticate.

keyPrefix (returned by the create, list and details endpoints) is the first 20 characters of the key followed by a literal .... It is a display label, not a usable credential.

Using the Key

Include it in every request via the X-API-Key header:

curl https://api.kolbo.ai/api/v1/models \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript (fetch):

async function main() {
  const response = await fetch("https://api.kolbo.ai/api/v1/models", {
    headers: { "X-API-Key": "YOUR_API_KEY" }
  });
  const data = await response.json();
  console.log(data);
}
main();

Python (requests):

import requests

response = requests.get(
    "https://api.kolbo.ai/api/v1/models",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())

Optional: Tagging a Session

Every request may additionally carry X-Kolbo-Caller-Session-Id, a stable identifier you choose for one run of your integration. Credit deductions made while it is present are tagged with it, so you can later ask what a whole run cost — see Credits & Billing.

curl https://api.kolbo.ai/api/v1/models \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Kolbo-Caller-Session-Id: run-2026-07-27-a"

Managing Keys

List Keys

curl https://api.kolbo.ai/api/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns { "status": true, "data": [ ... ] }, newest first. The list is not filtered — revoked and expired keys are returned alongside live ones. Read isActive and isExpired rather than assuming every row is usable.

The list also includes keys minted automatically by Kolbo sign-in flows (Kobi Code, the desktop app, connectors), so expect rows you did not create in the Developer Console.

Get Key Details

curl https://api.kolbo.ai/api/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns the same field set as one list row (minus billingMode), under data. A key id that does not exist returns 404; one that exists but belongs to someone else returns 403 — unlike the reveal endpoint, which collapses both into 404.

Revoke a Key

curl -X DELETE https://api.kolbo.ai/api/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns { "status": true, "message": "API key revoked successfully" }. An unknown key id returns 404; a key that belongs to someone else returns 403. Requires a JWT — see the table above.

Revocation is immediate and permanent — there is no un-revoke. The key stays in the list with isActive: false.

Permission Scopes

A key carries read, write, or both.

• Safe methods (GET, HEAD, OPTIONS) are always allowed, whatever the key's scope.
• A key without write (or admin) is blocked on every mutating request, returning 403 with code API_KEY_READ_ONLY.
• A few routes enforce write permission on every key, including grandfathered ones, and return 403 for a key without write:
  • POST /api/v1/music-library/clean/{trackId} and POST /api/v1/music-library/import (paid music; code API_KEY_READ_ONLY)
  • POST /api/v1/projects/{id}/transfer, POST /api/v1/project-transfers/{id}/accept, POST /api/v1/project-transfers/{id}/decline, DELETE /api/v1/project-transfers/{id} (code API_KEY_READ_ONLY)
  • POST /api/v1/downloads (no code; body { "error": "API key requires write permission" })
  • POST /api/v1/editor/sessions, PATCH /api/v1/editor/sessions and POST /api/v1/editor/exports (code FORBIDDEN)
  • Every Flows write and run: POST /api/v1/flows, PATCH /api/v1/flows/{flowId}, POST /api/v1/flows/{flowId}/ + snapshot, undo, duplicate, move, trash, restore or runs, and POST /api/v1/flows/{flowId}/runs/{runId}/cancel or /retry (code FORBIDDEN)

Limits

• Expiration is required — every key has an expiresAt. Default 365 days, clamped to 1–730 days.
• Permissions: read and write only (admin keys cannot be self-created).
• Key creation is rate limited to 10 attempts per hour per user; the reveal endpoint to 30 per minute. Both return 429 with { "status": false, "message": "...", "retryAfter": <seconds> } (3600 for create, 60 for reveal).

When a Key Stops Working

An otherwise valid key is rejected when any of these are true:

Every 401 above shares one body — { "message": "...", "tokenExpired": false } — with no code field. Distinguish them by reading message, not by branching on a code.

Keys are not auto-revoked during the deletion grace window, so restoring an account brings its existing keys back without re-creating them.

Security Best Practices

• Store keys in environment variables, never in code
• Use separate keys for different integrations
• Revoke unused keys promptly
• Monitor usage via the key details endpoint — every successful authentication bumps usageCount and lastUsed

Related