API keys

API keys authenticate software, never people. K-Block has two kinds, and each works in exactly one place:

• A gateway key belongs to one agent. The agent presents it to the Gateway to list and call tools. Its agent's policy and delegation decide every call made with it.
• A management key belongs to the organization. Scripts present it to the Cloud API, and its scopes decide what they may read or change.

A gateway key is refused by the Cloud API, and a management key is refused by the Gateway. People always sign in to the dashboard instead.

This page explains how keys are built, stored, limited and revoked. For the dashboard steps, see API keys in the dashboard.

Key format

Every key has the same shape:

kb_<environment>_<prefix>_<secret>

For example, a key looks like kb_live_<12 characters>_<43 characters>. The dashboard identifies a key by its non-secret part, shown as kb_live_<prefix>_… in the Key column, so you can match it to a secret store or a log line without revealing it.

The environment is recorded on every action made with a gateway key and inside the action's signed evidence. Observe windows also use it: a window covers the environments chosen when it is started, and relaxes only calls made with keys of those environments. The environment is a label, not a separate sandbox: test and live keys of an agent reach the same tools, upstream servers and delegations. For that reason every observe window, even a test-only one, needs the owner's permission for live traffic (see Observe and shadow).

The TypeScript and Python clients check the format before they send anything and throw KBlockAuthError with code MALFORMED_API_KEY for a value that cannot be a key, for example one with a trailing newline.

Shown once, stored as a keyed hash

The full key is returned exactly once, in the response that creates it. The dashboard shows it in a one-time panel: "Copy it now and store it in your agent's secret store. It will not be shown again."

K-Block never stores the key itself: it stores only the prefix and an HMAC-SHA256 of the secret, keyed with a secret that only K-Block holds. Nobody can read a key back from K-Block, the dashboard or the Cloud API. If you lose a key, revoke it and create a new one.

When a key is presented, K-Block looks it up by its prefix and compares the keyed hash in constant time. For an unknown prefix it still computes the keyed hash and a constant-time comparison, so the check itself does not reveal which prefixes exist.

Who can create and revoke keys

Approvers and viewers do not see API keys in the dashboard's navigation, and the Cloud API refuses their key requests. API keys themselves can never create, list or revoke keys. See Roles and permissions.

Create a key

In the dashboard, open API keys and select New API key. Owners and admins first choose the Kind; developers can create only gateway keys.

The Cloud API equivalent is POST /api/v1/orgs/<org-id>/api-keys, for a signed-in person only. It answers 201 with api_key, the key's record, and secret, the full key.

// Request body for a management key (example values)
{
  "name": "nightly-report",
  "kind": "management",
  "environment": "live",
  "scopes": ["read", "receipts:read"],
  "expires_at": "2027-01-31T00:00:00Z" // optional
}

A gateway key needs agent_id and no scopes; a management key needs scopes and no agent_id. The number of keys that are not revoked is limited by your plan; creating one more is refused with 402 PLAN_LIMIT_EXCEEDED. Expired keys still count until they are revoked, so revoke them to free capacity.

Keys cannot be edited after creation. To change a name, scopes, agent or expiry, create a new key and revoke the old one.

Use a key

A gateway key goes in the Authorization header of the agent's MCP connection to the Gateway:

POST /mcp HTTP/1.1
Host: gateway.example.com
Authorization: Bearer kb_live_<prefix>_<secret>
Content-Type: application/json

The Gateway authenticates every request on its own, so there is no session to expire. See Set up an agent and the TypeScript client.

A management key goes in the same header on Cloud API requests:

GET /api/v1/orgs/<org-id>/agents HTTP/1.1
Host: api.example.com
Authorization: Bearer kb_live_<prefix>_<secret>

A management key only reaches its own organization: any other organization ID answers 404.

Management key scopes

read does not include approvals or receipts; add approvals:read or receipts:read for those.

Whatever its scopes, a management key can never decide approvals, cancel actions, submit or revoke delegations, activate, roll back or emergency-stop a policy, start an observe window, change disclosure or organization settings, manage members, invitations, API keys or webhooks, read the audit log, set the principal identity or change the plan. Those need a signed-in person.

Expiry and last use

• Expiry. A key with an expiry time stops working at that time. The Status column then shows Expired. A key without one shows "No expiry" and works until it is revoked.
• Last used. K-Block records when a key last authenticated successfully, at most once a minute. The Last used column shows the time, or "Never".

Expired and revoked keys stay in the list as a record. A key not shown as Active cannot authenticate. An active key can still be refused for the reasons in When a key stops working.

Revoke a key

Select Revoke on the key's row and confirm "Revoke this key? Requests with it fail immediately." The Cloud API equivalent is POST /api/v1/orgs/<org-id>/api-keys/<key-id>/revoke.

Revocation takes effect on the very next request, because every request checks the key again. There is no cache or grace period:

• An agent using a revoked gateway key gets 401 from the Gateway on its next request.
• A script using a revoked management key gets 401 UNAUTHENTICATED on its next Cloud API request.
• Actions that were already decided keep their recorded state and evidence. An approved call can still be executed by a request that authenticates with any other working gateway key of the same agent, including a key of the other environment. To stop an approved call from running, cancel the action or disable the agent.

Revoking an already revoked key answers 409 INVALID_STATE. Revocations cannot be undone. Every creation and revocation is recorded in the audit log as api_key.created or api_key.revoked.

When a key stops working

A key works only while all of these hold, checked on every request:

The last two rules mean a key never outlives its creator's authority. A management key created by an admin stops working if that admin becomes a developer, and every key a person created stops working when they leave or are removed.

K-Block also revokes these keys outright, so the change shows in the list and the audit log:

• Removed or left the organization: every key they created is revoked.
• Demoted: keys of a kind the new role cannot create are revoked (management keys when they are no longer owner or admin; all keys when they are no longer owner, admin or developer).
• Account deleted: when K-Block deletes a person's account, every key that person created is revoked, in every organization. Accounts cannot be deleted from the dashboard or through the Cloud API.

Each of these revocations carries a reason in the audit event: creator_removed, creator_left, creator_lost_role or creator_deleted.

Good practice

• Create one gateway key per agent and per environment the agent runs in, and name it after where it runs.
• Give management keys only the scopes a script needs, and an expiry when the script is temporary.
• Store keys in a secret manager or environment variable, never in source control.
• When a person who created keys leaves, create replacement keys under someone who stays before they are removed.