Agents API

PATCH /api/v1/agents/

Updates an agent's properties.

Token revocation on deactivation (Wave 1.5)

When active is set to false, the server now immediately revokes all existing OAuth tokens issued to that agent's client_id in addition to blocking new token issuance.

This ensures the UI promise is kept: "Deactivating will prevent new tokens and revoke all active tokens."

Audit event: agent.deactivated_with_revocation is written with metadata:

{ "revoked_token_count": <number> }

Previously issued tokens will return active: false on introspection and 401 on protected resource requests as soon as the PATCH completes.

Request body

Response

Returns the updated agent object (200 OK) or 404 if not found.

POST /api/v1/agents//rotate-dpop-key

Rotates the DPoP keypair binding for an agent. The caller supplies the new public key JWK; the server records it as the new cnf.jkt for future token issuance and revokes all tokens bound to the old key.

Auth: Admin API key required (Authorization: Bearer sk_live_...).

Request body

{
  "new_public_jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "<base64url>",
    "y": "<base64url>"
  },
  "reason": "scheduled rotation 2026-04-26"
}

Response (200 OK)

{
  "old_jkt": "aB3kQ...",
  "new_jkt":  "xZ9mR...",
  "revoked_token_count": 3,
  "audit_event_id": "audit_abc123"
}

Error responses

Audit event

Emits agent.dpop_key_rotated with metadata:

{
  "old_jkt": "...",
  "new_jkt":  "...",
  "revoked_token_count": 3,
  "reason": "..."
}