Revoke Agent

Permanently revoke a machine agent identity, terminating all sessions and blocking future operations

Revoke Agent

POST /v1/agents/{agentID}/revoke

Permanently revokes a machine agent identity. This is an irreversible operation that:

1. Sets the agent status to "revoked"
2. Invalidates all active sessions
3. Blocks all future tool invocations
4. Prevents the agent from being used in new delegations

Revocation is permanent and cannot be undone. If you need to temporarily disable an agent, use the suspend endpoint instead. Revoked agents remain in the system for audit trail purposes but cannot be reactivated.

Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

Path Parameters

agentID · string · required

The MAIP agent identifier (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH).

Request Body

reason · string · required

Human-readable explanation for the revocation. Permanently recorded in the audit log. Maximum 1024 characters.

Response

status · string

Updated status, always "revoked" on success.

agent_id · string

The MAIP agent identifier that was revoked.

Example

curl -X POST https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH/revoke \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Agent key compromised. Security incident SI-2026-0412. Replacement agent registered as maip:t1234567:01HYX9NPZS0TMHDO2YHOU0UFGJ."
  }'

---

When to Revoke vs. Suspend

Scenario	Action
Anomalous behavior detected, investigation pending	Suspend
Temporary maintenance or configuration change	Suspend
Agent key confirmed compromised	Revoke
Agent decommissioned from production	Revoke
Compliance or legal hold requires permanent disablement	Revoke

After revoking an agent, you can still view its full history via the GET /v1/agents/ endpoint. The agent record is retained indefinitely for audit compliance (SOC 2 Type II, ISO 27001).