Skip to main content
POST
/
v1
/
agents
/
{agentId}
/
revoke
Revoke Agent
curl --request POST \
  --url https://api.truthlocks.com/v1/agents/{agentId}/revoke \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "reason": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "display_name": "<string>",
  "description": "<string>",
  "scopes": [
    "<string>"
  ],
  "metadata": {},
  "trust_score": 0.5,
  "public_key": "<string>",
  "session_count": 123,
  "keys": [
    {
      "kid": "<string>",
      "algorithm": "<string>",
      "public_key": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

​
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

ScenarioAction
Anomalous behavior detected, investigation pendingSuspend
Temporary maintenance or configuration changeSuspend
Agent key confirmed compromisedRevoke
Agent decommissioned from productionRevoke
Compliance or legal hold requires permanent disablementRevoke
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).

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
agentId
string<uuid>
required

Agent identifier

Body

application/json
​
reason
string
required

Human-readable reason for revocation

Response

Agent revoked

​
id
string<uuid>
​
agent_type
enum<string>
Available options:
orchestrator,
worker,
inference,
pipeline,
service,
bot,
llm
​
display_name
string
Maximum string length: 256
​
description
string
​
status
enum<string>
Available options:
active,
suspended,
revoked
​
scopes
string[]
​
metadata
object
​
trust_score
number<float>
Required range: 0 <= x <= 1
​
public_key
string

Base64-encoded public key

​
session_count
integer
​
keys
object[]
​
created_at
string<date-time>
​
updated_at
string<date-time>