A delegation is a signed grant of authority. The organization principal signs it to authorize the Gateway to perform certain actions for one agent, until a set expiry. Without a valid delegation an agent can do nothing: every call its policy does not deny outright is denied with NO_DELEGATION, and its tool list is empty.
A delegation does not replace the policy. The delegation says which actions the Gateway may perform for the agent at all; the agent's policy still decides each call (allow, require approval or deny) within that grant.
What a delegation contains
| Part | What it is |
|---|---|
| Issuer | The organization principal. Only a delegation signed by the organization's current principal is used. |
| Delegate | The Gateway's service identity (its KID). The Gateway acts for the agent; it can never pass the authority on. |
| Organization and agent | The one organization and the one agent the grant is for. |
| Actions | The actions the Gateway may perform for the agent, for example refund.create, or a prefix pattern such as refund.*. The reserved kblock.task permission is required as well; the dashboard adds it automatically. |
| Spending limit (optional) | A maximum amount per call, with a currency. |
| Valid from (optional) | The delegation is not used before this time. |
| Expires | Required. The delegation is not used after this time. |
A delegation is a signed K-Block object. Once stored, the signed delegation cannot be changed or deleted (a revocation is recorded next to it), and it becomes part of the evidence of every action performed under it. To change what an agent may do, sign a new delegation (and revoke the old one if it should stop working).
Who signs, and where
Delegations are signed in the browser, with the principal's private key. The Cloud API and K-Block's database never receive or store that key: it is generated, stored and used in your browser by the dashboard's code (see How the browser stores keys).
Have the principal key in your browser
An owner generates the principal in Settings. Everyone else who should sign needs their own copy in their browser: the owner exports a key backup that contains the principal, and the other owner or admin imports it under Account → Key backup, signed in to their own account. A copy that another account stored in the same browser profile is not used for you. See The organization principal.
Open the agent
Open the agent's page. While the agent has no active delegation, the Authorize this agent form is already shown; otherwise select Sign a new delegation… in the Delegations card. Only owners and admins see the form.
Choose the grant
Select the actions under Actions of your exposed tools (or enter them in Other actions or patterns). Set the Expires time (90 days ahead by default) and, if you need them, Spending limit per call (optional) with its Currency and Valid from (optional).
Check the delegate and sign
Under Delegate, the form shows the KID of the K-Block Gateway, the identity that receives the authority. The form says that the KID shown is the Gateway identity the dashboard trusts, and your browser refuses to sign for any other; it is the same Gateway KID the dashboard shows right after you create a gateway API key. If the form shows the warning No gateway identity is pinned instead, the dashboard cannot confirm which Gateway identity to trust: compare the KID with the Gateway KID K-Block gave you, and if the dashboard keeps showing the warning, contact K-Block support. Then select Sign and submit delegation.
Do not sign if the form shows No gateway identity is pinned and you cannot compare the KID, or if it warns The gateway identity differs from this agent's earlier delegations and you did not expect that change: contact K-Block support first. If the form shows The gateway identity could not be verified — do not sign a delegation, it cannot be submitted: select Try again, and if the error stays, contact K-Block support and give them the error message and, if one is shown, its code.
Who may submit and revoke
The Cloud API accepts a delegation or a revocation only when both of these hold:
- The caller is a signed-in owner or admin. Approvers, developers, viewers and management API keys are refused.
- The object is signed by the right key. A delegation must be signed by the organization's current principal; a revocation must be signed by the principal that issued the delegation.
So an admin can submit delegations once their own account holds a copy of the principal key in their browser, imported from a key backup an owner gave them. The key, not the role alone, is the real control: decide deliberately who holds it, and replace the principal if a copy may be exposed or someone who holds one should no longer have it (see Replacing the principal).
When a delegation is submitted, K-Block also checks that:
- the delegate is K-Block's current Gateway identity, and the organization and agent are the ones in the request;
- it grants actions or prefix patterns such as
refund.*, but not*and nothing in thekblock.namespace besideskblock.task; it allows no further delegation and carries no constraint other than the spending limit; - the expiry is in the future, and the signing time is not more than 5 minutes ahead of K-Block's clock.
An agent can have at most 100 active delegations; one more is refused (CONFLICT, reason TOO_MANY_DELEGATIONS). Every delegation that is neither revoked, withdrawn nor expired counts, including ones not valid yet and ones from a replaced principal. Submitting the same signed delegation again is accepted without creating a second copy.
How a delegation is used on each call
For each call, the Gateway selects the agent's newest delegation that is usable now and grants the call's action. A delegation is usable when it is issued by the current principal to the current Gateway identity, is not revoked or awaiting revocation, has not expired, and its valid-from time and signing time have passed.
The selected delegation is recorded with the action and signed into its evidence. If no delegation is usable, the call is denied with NO_DELEGATION. The agent's tool list (tools/list) contains only tools whose actions a usable delegation grants.
The Delegations card lists each delegation with its state:
| State | Meaning |
|---|---|
active | From the current principal, not revoked, expired or before its valid-from time. Calls use it once its signing time has passed, and only while it names K-Block's current Gateway identity. |
not_yet_valid | Its valid-from time has not come yet. |
expired | Past its expiry. |
revoked | Revoked. |
revocation_pending | A revocation was refused (see below); the delegation is already withdrawn from use. |
superseded | Issued by a previous organization principal; it authorizes nothing any more. |
Revocation
To revoke, select Revoke on the delegation's row and confirm Sign revocation. The button appears only for owners and admins whose own account holds the principal's key in that browser. The revocation is a signed object, created in the browser with the principal's key, and takes effect at the time it was signed.
| What | Effect of the revocation |
|---|---|
| New calls | The delegation is no longer selected. Calls are denied with NO_DELEGATION unless another usable delegation grants the action. |
| Pending approvals | They can still be approved, but an approval can never make them run (see the row on approved calls). If the agent repeats the call before anyone decides, the pending action is closed as expired (SUPERSEDED) and the call is decided again. |
| Calls allowed but not yet executed | Not executed. They are closed as superseded on the next identical call. |
| Calls a person already approved | Never executed: each attempt is refused (VERIFICATION_FAILED) and the approval is not consumed. The action stays approved until it expires (TASK_EXPIRED) or someone cancels it. |
| Executions already in flight | They finish and their outcome is recorded, with a result dated before the revocation. |
When a revocation is refused
A revocation dated at or before an execution that is still in flight under the delegation is refused (CONFLICT, reason REVOCATION_PREDATES_EXECUTION), because it would invalidate a call that was already sent upstream. The refusal still withdraws the delegation from use at once and permanently (state revocation_pending): no new call selects it and no approval under it is consumed. Once the calls in flight have finished, select Sign revocation again to record the revocation. This can also happen when the signing browser's clock is behind K-Block's.
Expiry
Every delegation has an expiry, and K-Block never lets anything decided under it outlive it:
- After the expiry, the delegation is no longer selected and calls are denied with
NO_DELEGATION, unless another usable delegation grants the action. - Every open action decided under a delegation expires no later than the delegation: an approval request that is still open expires (
APPROVAL_EXPIRED), and an approved call that has not run expires (TASK_EXPIRED).
Delegations cannot be extended. Sign a new delegation before the old one expires; because the newest usable delegation is selected, calls move to the new one without a gap.