revoke_agent
- Category: auth
- Access: write
- Audience: administrative (ordinary users do not normally call this directly)
Purpose
Revokes a principal immediately, including all its live sessions. Call it to cut off a compromised agent entirely.
Arguments
Required: client_id.
Optional: reason.
-
client_id. -
reason.
Result
Object with revoked (echoed client_id), matched, and sessions_killed counts.
Boundaries
Conductor role required. Revocation bumps the principal generation so every live session denies on its very next operation.
Lifecycle / side effects
Moves the principal entry to revoked with a generation bump and revokes all its live sessions. History is retained for operator recovery.
Errors
Non-conductor callers get a requires-conductor error payload. Missing client_id is a tool error. Unknown principals report matched 0.
Example
{
"client_id": "<uuid>",
"reason": "key rotation"
}
Result shape:
{
"matched": 1,
"revoked": "<uuid>",
"sessions_killed": 2
}
See also
kill_session, list_sessions, revoke_ticket, issue_enrollment_ticket.