> For the complete documentation index, see [llms.txt](https://docs.antivamp.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.antivamp.io/production/11_key_rotation.md).

# Key Rotation & Revocation

## API keys (partner-held)

* **Rotate**: issue a new key, then revoke the old (dashboard "Rotate key", or operator-issued for production). Old key is rejected immediately after revocation (`key_revoked`). Overlap by deploying the new key before revoking.
* **Revoke**: operators revoke with an actor + reason (audited). Compromised keys should be revoked immediately; rotate the partner onto a fresh key.
* Keys are hashed at rest and never logged. `last_used_at` aids detection.

## Signing keys (AntiVamp-held, per environment)

* **Discovery**: `GET /v1/keys` and `GET /.well-known/antivamp-signing-keys.json` return all currently-accepted public keys with `kid`, `environment`, `status` (`active` / `retiring` / `revoked`).
* **Rotation without breakage**: set a new active signing key; publish the previous public key with `status: retiring` for an overlap window so decisions signed just before rotation still verify. Verifiers match by `keyId` — no code change needed.
* **Emergency revocation**: add the compromised `kid` to the revoked set; the verify path returns `revoked_key` and `/keys` marks it `revoked`. Rotate to a new active key at the same time.
* **Audit**: rotations and revocations are recorded as audit events.
* Private signing keys live only in server-side secret management — never in the repo, frontend, logs, or database rows.

## Verifier guidance (partners)

* Cache `/v1/keys` briefly (SDK caches 5 min); refresh on an unknown `keyId`.
* Accept any listed non-revoked key during overlap; reject `revoked` keys.
* Always enforce `expiresAt` — never trust a stale decision even if signed.

## Test matrix (shipped)

active key · retiring key · revoked key · unknown key · expired decision · future-issued decision · clock skew · modified payload · replayed nonce · wrong environment — covered by SDK + server verification tests.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.antivamp.io/production/11_key_rotation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.