Your first protected action

This walkthrough follows the dashboard's own setup guide, Set up K-Block on an organization's Overview: eight steps from an empty organization to an agent whose tool calls go through the Gateway. Each step below names the page, the fields and the buttons you use, and what must be true before the guide marks it done.

At the end you send a first call and find its action and its signed receipt. The quickstart then exercises all three outcomes (allowed, held for approval, denied) from your own code.

Before you start

• An account with a verified e-mail address. Sign up, then open the verification link K-Block e-mails you: you can sign in only once the address is verified. See Your account.
• An organization. When you sign in without one, the dashboard opens Create an organization; later, the organization switcher offers Create organization. Enter a Name and a URL slug and select Create organization. You become its owner, and the guide appears on its Overview.
• An MCP server reachable over Streamable HTTP at an https address without a query string, such as https://tools.example.com/mcp. The Cloud API must reach it to discover its tools, and the Gateway to call them. K-Block only connects to public https addresses: private, loopback and internal addresses are refused (URL_NOT_ALLOWED), so a server that has only such an address cannot be registered.
• One browser. The keys you generate in steps 1 and 2 are stored in this browser. Do every signing step in it, and export a key backup when you are done.

As the owner you can do every step yourself. Developer is for one user. Team membership starts with Startup. On the free Developer plan you are the organization's only member, so you also approve the calls your policy holds for approval; the templates' approval rules admit owners. In a team (Startup or a larger plan), the roles split the work:

Roles and permissions has the full matrix.

Set up the organization

1. Set the organization principal

   The organization principal is the organization's K-Block identity. It signs every delegation that lets the Gateway act for an agent, and every cancellation of an action.

   Open Settings. In the Organization principal card, optionally enter a label, then select Generate principal in this browser. The private key is generated in your browser and never sent to K-Block Cloud, which stores only the public identity.

   Then open Account settings (account menu), Key backup, and export a backup encrypted with a passphrase. Without a backup, a lost browser means generating a new principal and authorizing every agent again.

   The guide marks this step done once the organization has a principal.

2. Bind your personal identity

   Approvers sign their approvals and rejections with a personal key generated in their own browser.

   Open Account settings. In Personal K-Block identity, select Generate and bind. To approve from a second browser later, import a key backup of this identity there, or generate a separate identity for that device (up to five can be active).

   Every member who should approve calls does this once, in the browser they approve from, before the calls they should approve are made: the approvers of a request are fixed when the call is decided. A call that needs approval when no eligible member has a personal identity is denied with NO_APPROVERS.

   Done once you, the member viewing the guide, have an active personal identity.

3. Register an MCP server and expose tools

   Open Tools & MCP servers and select Register MCP server. Fill in:

   • Name;
   • URL, the server's Streamable HTTP endpoint;
   • Authorization header (optional): the complete header value your server expects, for example Bearer …. It is stored encrypted, sent unchanged by discovery and by the Gateway, and never shown again.

   Select Register server. On the server's page, select Discover tools: the Cloud API calls the server's tools/list and lists the tools it really offers. Nothing is exposed yet.

   For each tool your agent should use, select Expose… and fill in:

   • Action: the permission your policies and delegations refer to, for example refund.issue. The placeholder is only a suggestion from the tool's name; enter the action yourself.
   • Amount pointer (optional) and Currency: where the call's amount is, as a JSON Pointer such as /amount, and its ISO 4217 currency. Policies can only decide on amounts you map here.
   • Currency pointer (optional): where the call names its currency, if the tool takes one, such as /currency. A call naming another currency, or none, is then denied with INVALID_AMOUNT.
   • Exposed name (what agents see at the Gateway), Description, and Enabled (callable through the gateway).

   As an owner or admin, select Expose tool: the tool is enabled and its upstream binding (server, URL, credential, action, amount mapping and input schema) is authorized in the same step. A developer's Save as disabled draft waits for an owner or admin to enable it: on Tools & MCP servers, they select Edit on the tool, check Enabled (callable through the gateway) and select Save tool, which also authorizes its binding.

   Done once at least one tool is callable: enabled, on an active server, with an authorized binding. See Connect an MCP server and Expose and map tools.

4. Activate a policy

   A policy decides each call: allow, require approval or deny. Its rules refer to the actions you mapped in step 3.

   Open Policies, select New policy, and under Start from pick a template, for example Support refunds. Enter a Name, adjust the template's Parameters if needed, and select Create draft. The page that follows shows how the draft covers your exposed tools; check its warnings, then select Open the policy. (With Blank (deny-all), Create policy opens the policy's editor instead, where you write the first version.)

   Nothing is enforced while the version is a draft. On the policy's Rollout tab, select Review and activate v1, review the sheet (the rules, a simulation over recent calls, the saved example calls) and select Activate v1. Only owners and admins activate; the change applies to the next call.

   Done once an active policy exists. See Create a policy.

5. Create an agent

   An agent is the record your AI application calls tools under. It is bound to one policy.

   Open Agents, select New agent, enter a Name, choose the Policy you activated, and select Create agent. Without a policy, every call of the agent is denied (NO_POLICY). The dashboard opens the agent's page.

   Done once an active agent exists. See Set up an agent.

6. Authorize the agent

   A delegation is the organization principal's signed permission for the Gateway to act for this agent, for a list of actions, until it expires. The Gateway shows an agent only the tools whose action a valid delegation grants.

   On the agent's page, the Authorize this agent card is open while the agent has no delegation (later, use Sign a new delegation…). Check the Delegate: it shows K-Block Gateway and its KID. Your browser has verified that this KID belongs to a valid K-Block service identity and, unless the form warns that no gateway identity is pinned, that it is the Gateway identity the dashboard trusts. If either check fails, the form shows The gateway identity could not be verified — do not sign a delegation and cannot be submitted; reload the page, and if the message stays, contact K-Block support with the message it shows, including its code if there is one. If the form shows the warning No gateway identity is pinned, the dashboard does not know which Gateway identity to trust, so your browser cannot confirm that this KID is K-Block's Gateway: before you sign, compare it with the Gateway KID that K-Block gave you. If they differ, or you have no Gateway KID to compare with, do not sign and contact K-Block support. Then:

   • under Actions of your exposed tools, select the actions the agent may use (kblock.task is added automatically); Other actions or patterns accepts more, such as refund.*;
   • optionally set a Spending limit per call and its Currency, and Valid from. With a spending limit, every call of a tool without an amount mapping is denied (CONSTRAINT_VIOLATION), so leave it empty if the agent uses such tools;
   • check Expires (90 days ahead by default).

   Select Sign and submit delegation. The principal's key must be in this browser; if it is not, import your key backup under Account settings, Key backup.

   Done once an agent has a delegation from the current principal that is neither revoked nor expired. The guide does not check Valid from: until that time the delegation authorizes nothing, and calls it would cover are denied NO_DELEGATION although the step shows done. See Delegations.

7. Create a Gateway API key

   The agent presents a gateway API key to the Gateway; the key decides which agent is calling.

   On the agent's page, in Gateway API keys, select Create a gateway key (or open API keys and select New API key). Enter a Name, choose the Environment (Live or Test, recorded on every action made with the key), check the Agent, optionally set Expires, and select Create key.

   Copy the key now: it is shown once, and only a keyed hash is stored. The same notice shows the Gateway MCP endpoint and the Gateway KID, each with a copy button. If it does not show them, contact K-Block support for the missing value. You need the Gateway URL to connect the agent and the KID to check receipts.

   Done once an agent has a gateway key that is not revoked; the guide does not check whether the key has expired. See API keys.

8. Send the first call through the Gateway

   Point your agent's MCP client at the Gateway's MCP endpoint, <Gateway URL>/mcp, with the key as its bearer token (Authorization: Bearer kb_live_…). With the TypeScript client, in a program that reads them from two environment variables of its own (set KBLOCK_GATEWAY_URL to the Gateway URL and KBLOCK_API_KEY to the agent's gateway API key):

   import { connectKBlock, explainResult } from "@kblockai/client";
   
   const client = await connectKBlock({
     gatewayUrl: process.env.KBLOCK_GATEWAY_URL ?? "",
     apiKey: process.env.KBLOCK_API_KEY ?? "",
   });
   
   // Only the tools the agent's delegation grants are listed.
   const tools = await client.listTools();
   console.log("tools:", tools.map((t) => t.name).join(", "));
   
   // Replace with one of your exposed tools and its arguments.
   const result = await client.callTool("lookup_order", { order_id: "ord_123" });
   console.log(explainResult(result));
   
   await client.close();

   The quickstart shows how to install and run it, in TypeScript and Python. A denial counts for the guide too: the step is done once the organization has its first recorded protected action.

When all eight steps are done, the guide disappears from the Overview.

Find the action and its receipt

Every call the Gateway decides is recorded as a protected action, whether it was allowed, held or denied. A call refused before any decision, for example for an unknown tool name or invalid arguments, is not recorded, and neither is a call denied with TOOL_REAUTHORIZATION_REQUIRED.

1. Open Actions. The newest action is at the top, with its decision and its status; filter by status or agent if needed.
2. Open the action. Its page shows the lifecycle, why the policy decided as it did, the exact call (tool and arguments) and the policy decision.
3. If the call needed approval, its status is pending_approval: open Approvals, open the request, check the call and select Approve and sign. The call then executes once when the agent repeats it with the same arguments and idempotency key (resume or waitForApproval in the clients), or at once if the agent is still waiting.
4. Once the call has run, the action's page links to its receipt: select Open and verify receipt.
5. On the receipt's page, select Verify in this browser to check every signature locally, or Download .kbundle to keep the file and verify it offline.

A call denied when it was decided, and an approval request that expired, have no receipt. Rejected and cancelled calls do. See Actions and Receipts.

What can go wrong

More causes in Gateway and tools and Policies and approvals.

Next steps