opschain admin agent revoke

packs:agents

opschain admin agent revoke <agent-id> --reason <text> [--server <url>] [--auth-token <token>]

Revokes one agent (v2 AgentService.RevokeAgent): its public key is tombstoned and its channel and proxied sessions are severed immediately. The identity stays refused until it re-enrols with a fresh keypair and a fresh registration token — revocation is permanent for that key, unlike halt (reversible, same identity) and forget (housekeeping for a stale registration).

The revoke is break-glass audited: --reason is required (a whitespace-only reason is refused by name) and is recorded with the acting identity on the agent:revoked audit event, so the agent's timeline answers why the identity was retired.

After the revoke the id disappears from the admin views: on the live fleet verbs a revoked id answers 404 exactly like an unknown one, so the tombstone itself is never exposed. The revocation is recorded as an audit event on the agent's timeline, and the history is never erased — opschain admin agent activity <member-id> keeps answering the departed agent's read-only timeline, marked departed (opschain docs cli/admin-agent-activity).

<agent-id> is the agent's member id — the ID column of opschain admin agents list.

Flags

Flag	Meaning
--reason <text>	Break-glass reason, recorded on the audit event. Required — and it must be non-blank: the server refuses a whitespace-only reason.
--server <url>	Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>	Admin bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Output

Always a machine document (JSON unless -o yaml):

{
  "id": "01999a7e-…",
  "revoked": true
}

Exit codes

Code	Meaning
0	The agent was revoked.
1	The server refused or failed the request (including a rejected admin token, or an unknown id).
2	Usage — wrong arguments, a missing --reason, or no server / admin token resolvable.

Named errors

• --reason is mandatory: revoking an agent is break-glass audited — exit 2.
• a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' — exit 2.
• this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login' — exit 2.
• the server rejected the credential — run 'opschain login' again, or check the admin token — exit 1.
• agent <id> is not known to this estate — admin agent verbs take the ocr_ member id from 'opschain admin agents list' (a UUID is usually the identity-side service_account_id, not the member id) — the unknown (or already revoked) id 404, exit 1.

See also

• opschain docs cli/admin-agent-halt — reversible emergency stop, same identity.
• opschain docs cli/admin-agent-forget — remove a stale registration without refusing the identity.
• opschain docs cli/admin-agent-token-create — mint the registration token a replacement agent enrols with.