Architecture at a glance

K-Block has two paths. Members work in the dashboard, which talks to the Cloud API. Agents call tools through the Gateway. Both paths work on the same records of your organization, so what a member does in the dashboard (activate a policy, approve a call, revoke a key) takes effect at the Gateway right away.

This page shows both paths, which part of K-Block each task happens in, what to give your agent, and which keys and credentials each part holds.

The management path

Every dashboard page loads its data in your browser, from the Cloud API, through the dashboard you signed in to. Your session authenticates these requests.

A script with a management API key calls the Cloud API directly, at the Cloud API base URL that K-Block gives you, not through the dashboard: the dashboard does not pass API keys on. See Cloud API.

When the dashboard cannot reach the Cloud API, or the Cloud API does not answer a request within 60 seconds, the page shows "The dashboard could not reach the K-Block service. Try again in a moment." Reload the page and try again; if it continues, contact K-Block support and tell them when it happened. The dashboard cannot reach the Cloud API describes this error and how it differs from a problem with your own connection.

Objects that must be signed by a person are signed in the browser before they are sent: the organization principal signs delegations and cancellations, a member's personal key signs approvals and rejections. The Cloud API checks each signature and stores the object; it never receives the private keys.

The tool-call path

1. The agent connects to <Gateway URL>/mcp with its gateway API key as the bearer token. The Gateway is stateless: it authenticates every HTTP request again, so a revoked key fails on the next request.
2. tools/list returns only the tools the agent may use: enabled tools on an active server, whose upstream binding an owner or admin authorized, and whose action a valid delegation grants to this agent.
3. On tools/call, the Gateway applies the agent's active policy version as it is at that moment (so a policy change applies to the next call), checks the delegation and the approvers, signs the request and records the decision.
4. An allowed call, or an approved one, is consumed once and sent to the upstream MCP server with the Authorization header you stored for that server.
5. The Gateway signs the result, stores the receipt, records the outcome and answers the agent with the tool's result and the receipt's IDs.

How an approval reaches a waiting call

When a call needs approval, the Gateway records an approval request and answers approval_pending. An approver opens it in the dashboard and signs the decision in the browser; K-Block records the decision and the Gateway is notified right away. An agent that asked the Gateway to wait (the kblock/wait-seconds hint) is woken and the call runs. The Gateway waits at most 60 seconds by default and shortens a longer requested wait to that limit. An agent that did not wait retries the same call and gets the approved execution, once.

Components

Some work happens without a call or a click. K-Block delivers webhooks to your endpoints. It marks a request that nobody decided as expired within about 15 seconds after its time ends. It closes an execution that was interrupted, for example because the Gateway stopped during the call, as failed: normally between about 11 and 15 minutes after it started, with a receipt when its evidence still verifies (see Recovery of interrupted executions). It closes observe windows whose end has passed, with an agent.observe_ended audit event and webhook for each; a window relaxes nothing after its end either way. It e-mails address-verification links, password resets and invitations. An owner manages the organization's plan on the Billing page; when paid plans cannot be bought there, that page says so, for example with Billing is not configured in this environment.

Keys and identities

K-Block separates the keys that sign evidence from the credentials that authenticate requests.

Each identity is known by its KID, a kid:kb:… string derived from its public key. When you verify a receipt, compare its issuer with the Gateway KID. See Identities and KIDs.

What this means for you

• To protect an agent you need three things: the Gateway URL, a gateway API key for the agent, and the Gateway's KID to check receipts. The dashboard shows the Gateway's MCP endpoint (the Gateway URL followed by /mcp) and the Gateway KID right after you create a gateway API key. If it does not show them, contact K-Block support. The quickstart uses exactly these.
• Your MCP server must be reachable by K-Block at a public https address: by the Gateway for every call, and by the Cloud API when you discover and expose its tools in the dashboard. Plain http and private, loopback and internal addresses are refused (URL_NOT_ALLOWED when you register or change the server).
• Keep the principal's key safe. It lives in one browser until you export a backup; without it nobody can authorize new agents or cancel actions.
• When K-Block cannot record decisions, calls stop. The Gateway fails closed: it refuses with DATABASE_UNAVAILABLE (as the call's refusal, as an error of tools/list, or as HTTP 503 with a Retry-After header when it cannot even check the API key), and it never calls your tool without first recording that the call is being executed. Retry the same call later, unless the refusal says retryable: false (then check the action in the dashboard first). If the refusal continues, contact K-Block support with the code, the request ID of the Gateway's answer (its X-Request-Id header) and the time it happened.

Next steps