# Security: Credential rotation

Issue, protect, rotate, and revoke HMAC credentials without interrupting agent delivery verification.

Source: https://anywe.dev/docs/api/security-credentials

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.

> **Do not log secrets** Do not put an issued secret in application logs, support tickets, source control, or a client-visible error. If the value is lost, issue a replacement instead of expecting a read endpoint to recover it.

## 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.