Search docs

    Get the app
    View Markdown

    Keys

    Scoped, preset-based API keys.

    Generated from the contract, version 2.0.0-draft.2 (OpenAPI). Base URL https://usekabu.com/api. Errors are problem details, each code with its own page.

    Create a key (subset of the caller's scopes)

    POST/v2/api_keys
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: keys:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

    Request body: ApiKeyCreate.

    Status Means Body
    201 OK ApiKeyWithSecret
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/api_keys" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

    List keys

    GET/v2/api_keys
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: keys:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    limit query integer, from 1 to 100 Optional
    after query string Optional Opaque cursor from next_cursor.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK ApiKeyList
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/api_keys" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Revoke a key now

    DELETE/v2/api_keys/{key_id}
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: keys:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    key_id path string Required A key_… id.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    204 Done
    4XX Error Problem
    5XX Error Problem 
    curl -X DELETE "https://usekabu.com/api/v2/api_keys/$KEY_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Rotate; the old secret works for grace_seconds

    POST/v2/api_keys/{key_id}/rotate
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: keys:write.
    • Signed-in humans: admin.
    Parameter In Type Required Description
    key_id path string Required A key_… id.
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

    Request body (optional): ApiKeyRotate.

    Status Means Body
    200 OK ApiKeyWithSecret
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/api_keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

    Schemas

    ApiKeyCreate

    Property Type Required Description
    name string, at most 80 characters Required
    preset KeyPreset Optional Speaking as an agent and speaking as a human never share a key. agent (default): messages:write, messages:read, sessions:write, sessions:read, claims:write, media:write, events:read. service: answers:delegate, steer:write, recipients:write, webhooks:write, messages:read, sessions:read, events:read; never messages:write. admin: projects, agents, webhooks, keys, org, usage, observability and the agent scopes; never answers:delegate or steer:write. A key holding messages:write together with answers:delegate or steer:write is refused with 400 incompatible_scopes.
    scopes array of Scope, unique items Optional Overrides the preset; must be a subset of the caller’s. messages:write never combines with answers:delegate or steer:write.
    project ProjectRef Optional A project slug (auto-created on first use) or prj_… id. Omit for default. A slug that normalises (lowercase, letters and digits only) to an existing project’s key names that project, so My App, my-app and my_app are one project. Automatic creation stops at 1,000 live projects per org and mode with 429 quota_exceeded; existing projects stay usable. Nothing remembers a deleted project (projects.delete): the next message that names its slug creates a fresh one.
    agent string Optional
    default_to RecipientRef Optional rcp_…, ext:<your external id>, or me (the key’s default_to).
    mode string, one of "live", "test" Optional
    expires_at Timestamp or null Optional

    Unknown properties are refused.

    KeyPreset

    Speaking as an agent and speaking as a human never share a key. agent (default): messages:write, messages:read, sessions:write, sessions:read, claims:write, media:write, events:read. service: answers:delegate, steer:write, recipients:write, webhooks:write, messages:read, sessions:read, events:read; never messages:write. admin: projects, agents, webhooks, keys, org, usage, observability and the agent scopes; never answers:delegate or steer:write. A key holding messages:write together with answers:delegate or steer:write is refused with 400 incompatible_scopes.

    Type: string, one of "agent", "service", "admin".

    Scope

    Type: string, one of "messages:write", "messages:read", "messages:urgent", "sessions:write", "sessions:read", "steer:write", "claims:write", "answers:delegate", "media:write", "events:read", "projects:write", "agents:write", "recipients:write", "webhooks:write", "keys:write", "org:write", "usage:read", "observability:read".

    ApiKeyWithSecret

    Type: ApiKey and object.

    ApiKey

    Property Type Required Description
    object "api_key" Required
    id string Required
    name string Required
    preset string Required
    scopes array of string Required
    mode string Required
    project string or null Required
    agent string or null Required
    default_to string or null Required
    prefix string Required First 12 characters, for identification.
    last_used_at Timestamp or null Required
    expires_at Timestamp or null Required
    created_at Timestamp Required

    ApiKeyList

    Property Type Required Description
    object "list" Required
    data array of ApiKey Required
    has_more boolean Required
    next_cursor string or null Required

    ApiKeyRotate

    Property Type Required Description
    grace_seconds integer, from 0 to 604800 Optional

    Unknown properties are refused.