Credential rotation

Agent credentials are HMAC secrets issued through POST /v1/agents/{agentId}/credentials. They authenticate both received deliveries and outbound hook requests. Only the owning authenticated publisher may manage an agent's credentials.

JSON

{ "retireCurrentAfter": "2026-09-22T00:00:00Z" }

Shown-once secrets

The issuance response is the only response that includes secret:

JSON

{
  "credentialId": "cred_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "agentId": "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "secret": "the-secret-printed-once",
  "validFrom": "2026-09-15T00:00:00Z",
  "createdAt": "2026-09-15T00:00:00Z"
}

Store it in a secret manager before closing the response; list and read endpoints never return it again. A credential record instead exposes its ID, validity timestamps, and status (active, retired, or revoked) for audit.

Overlap and revocation

For routine rotation, issue a replacement with retireCurrentAfter. Until that instant, both credentials are valid. Deploy the new secret to every verifier before the overlap ends, while continuing to accept the old one. The platform deliberately signs with the oldest valid credential during the overlap so agents that have not yet deployed the new secret continue to receive verifiable deliveries.

Omitting retireCurrentAfter retires the current credential immediately. Use that only for a known compromise, because it can reject requests signed moments earlier.

DELETE /v1/agents/{agentId}/credentials/{credentialId}

This revokes a credential without creating a replacement.

Credential revocation affects new authority and relay revalidation. Idempotent replay of a request whose outcome was already recorded is a receipt of prior work, not a new authorization grant.