revoke_token
Revoke an agent's token to terminate its access. Optionally generate a recovery token so the agent can re-register.
Instructions
Invalidate another agent's token (v2.1 Phase 4b.1 v2).
When to use: confirmed compromise, lost device, or graceful retirement of an agent name. For routine key-hygiene rotation prefer rotate_token / rotate_token_admin (those keep identity). For removing the agent entirely use unregister_agent.
Behavior: transitions the target row to auth_state='recovery_pending' (when issue_recovery=true, also returns a one-time recovery_token the operator hands off out-of-band; the agent re-registers via register_agent with that token to mint a fresh agent_token) or auth_state='revoked' (terminal, only unregister_agent + register_agent can reuse the name). Original token_hash is preserved for forensic correlation; the state column, not the hash, enforces rejection. v2.6.2 R1: the per-instance vault file at <instanceDir>/agents/<name>.token is also scrubbed on every successful revoke (best-effort, ENOENT-safe) — the security boundary already held via the state check, but the scrub aligns the mental model so revoke_token leaves no credential on disk. Requires revoke_others capability.
Returns: { success: true, revoked: target_agent_name, revoked_by, revoked_at: ISO, changed: boolean, auth_state_before, auth_state_after, note }. When issue_recovery=true and the call actually changed state, also includes recovery_token (shown ONCE), recovery_note, and recovery_reissued: boolean. changed=false is an idempotent no-op (target was already revoked).
Errors: AUTH_FAILED (caller missing revoke_others), NOT_FOUND, RATE_LIMITED.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_token | No | Your agent token (from register_agent response). Optional here — also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header. | |
| revoker_name | Yes | Name of the agent performing the revoke — must hold the 'admin' capability. | |
| issue_recovery | No | v2.1 Phase 4b.1 v2: if true (default), issue a one-time recovery_token returned on this response (shown ONCE). Target can re-register with that token to resume as 'active'. If false, revocation is terminal — operator must unregister_agent + register_agent to recreate the row. | |
| target_agent_name | Yes | Name of the agent whose token to revoke. |