🧪 Beta — Available today; the interface contract may still change.

Revocation and incident response

"Can you stop it right now?" is a mandatory question in every security review, and this page gives you the honest answer: each recall layer differs in speed and reach. Blurring them is how you create a misjudgement during an incident.

By the end of this guide you will know:

• What each of the four recall layers stops, and how fast
• What order to act in during an incident
• Why "short lifetimes" matter more than "revocability"

The four recall layers

Layer	Action	Reach	Effective
1. Access key	Disable or rotate the access key (enable: false / rotate)	That key's ability to start new delegations	Immediate — no new delegate token can be issued after it is disabled
2. An already-issued delegate token	Wait for it to expire	The one token already in the agent's hands	Governed by the token's lifetime (settable at issuance, 60-86400 seconds)
3. Resource-side deny list	Reject by act.agent_id or grant_id in your own API or gateway	Your own resource services	Immediate (you implement it — see below)
4. The whole agent	Kill switch for that agent	All of that agent's grants and dispatches	See the Roadmap note below

There is no API to revoke a single grant

There is currently no API that revokes one grant by grant_id. Only two recall actions take effect immediately: disabling the access key (cuts off further issuance) and your own resource-side deny list (cuts off already-issued tokens). Precise revocation by grant_id is a roadmap item and ships together with the agent-level kill switch.

Layer 2 is the fact to design around

A delegate token already in an agent's hands cannot be invalidated individually within its lifetime. Which means: your real upper bound on recall speed is the lifetime you set at issuance.

So expiresIn is not a field to fill in casually — it is your risk window:

• Task-level delegations: 5-15 minutes, use and discard
• Session-level delegations: 1-2 hours
• Only reach toward the 24-hour maximum for scenarios you are certain are long-lived and low-risk

A runtime token deny list (immediate interception of already-issued tokens) is an explicit direction of travel, but until it exists, short lifetimes are the only reliable recall mechanism.

Layer 4: the agent-level kill switch

🚧 Roadmap — The agent-level kill switch is a control-plane capability and ships with agent registration and governance (see The agent identity model). Its design goal is to stop all in-flight and future grants for one agent in a single action. Until then, agent-level containment comes from combining two steps for a close equivalent: disable the access key it uses (layer 1) plus reject by act.agent_id on the resource side (layer 3) — which is exactly why we recommend a dedicated key per agent: disabling one affects only that agent.

Incident response checklist

When you suspect an agent is being abused or a credential has leaked, act in this order:

1. Stop the source first: disable the relevant access key (layer 1). This instantly cuts off the ability to issue new delegations — your first stitch.
2. Compute the risk window: check the remaining lifetime of tokens already issued but not yet expired (layer 2). That number is "how long an attacker can still operate in the worst case" — it decides whether you need to act on the resource side.
3. Reject at the resource side (when the window is unacceptable, which it usually is): reject requests carrying a specific act.agent_id or grant_id at your API gateway (layer 3). This is the only way to cut off an already-issued token inside its lifetime, and it requires your resource side to support it in advance (how: Protect your APIs).
4. Scope the incident from the audit trail: pull the full chain by audit_id / grant_id to confirm what actually happened and which data was touched (see Audit and compliance reporting).
5. Rotate and review: rotate the key and redistribute it; review the scope and lifetime settings — incidents are rarely "we could not revoke", they are usually "we granted too much, for too long".

Prevention beats response

Practice	Why it works
Size lifetimes to the task, not to the maximum	Directly compresses the risk window — the single most effective control
Keep the key's allowedScopes / allowedAgents minimal	Limits what can be delegated at all (see API reference)
A dedicated key per agent	An incident means disabling one key, without collateral damage
Resource-side support for rejecting by agent_id / grant_id	Leaves yourself a last-resort cut-off
Rotate keys on a schedule	Shortens how long any credential is exposed

FAQ

Can users revoke on their own? The user-facing "withdraw access" entry point is something your application implements — we recommend a "my authorizations" page (see Audit and compliance reporting) so users can see what is currently active. On the platform side, withdrawal lands across the layers above: stopping further issuance is immediate; tokens already issued are governed by their lifetime. Precise revocation by grant_id ships with the roadmap item.

Is the recall action itself recorded? Yes. Key disablement, rotation and other recall actions enter the audit chain as events: who withdrew what, and when (see Audit and accountability chain).

What happens to the agent after a token expires? The call fails with a token-expired error (the SDK throws QoniTokenExpiredError). Your application should catch it and decide whether to start a new delegation or end the task.

Next steps

• Audit and compliance reporting — scoping the incident afterwards.
• Protect your APIs: resource-side integration — how to build the cut-off.
• Security considerations — the full threat model and hard constraints.