---
title: "Manage Keys"
url: "https://docs.caracal.run/architecture/crypto-keys/"
markdown_url: "https://docs.caracal.run/markdown/architecture/crypto-keys.md"
description: "Key material, signatures, HMACs, JWKS, and rotation boundaries in Caracal."
page_type: "architecture"
concepts: []
requires: []
---

# Manage Keys

Canonical URL: https://docs.caracal.run/architecture/crypto-keys/
Markdown URL: https://docs.caracal.run/markdown/architecture/crypto-keys.md
Description: Key material, signatures, HMACs, JWKS, and rotation boundaries in Caracal.
Page type: architecture
Concepts: none
Requires: none

---

Caracal uses separate keys for encryption, mandate signing, audit integrity, stream integrity, and service-to-service exchange.

## Key Map

| Material | Used by | Purpose |
| --- | --- | --- |
| Zone signing keys | STS | Sign mandate JWTs and publish public keys through JWKS. |
| `ZONE_KEK` | API and STS | Encrypt/decrypt zone secrets and key material. |
| `AUDIT_HMAC_KEY` | API, STS, Gateway, Audit, Control | Protect audit event integrity. |
| `STREAMS_HMAC_KEY` | API, STS, Gateway, Coordinator, Audit/consumers | Sign Redis stream messages in published modes. |
| `GATEWAY_STS_HMAC_KEY` | Gateway and STS | Authenticate Gateway token-exchange requests to STS. |
| Admin and Coordinator tokens | API, Coordinator, Console, Control | Authenticate management and agent/delegation operations. |

## Mandate Verification

```mermaid
sequenceDiagram
  participant STS
  participant Client
  participant Resource
  STS->>Client: signed mandate JWT
  Resource->>STS: GET /.well-known/jwks.json
  STS-->>Resource: public keys with cache headers
  Client->>Resource: bearer mandate
  Resource->>Resource: verify signature, issuer, audience, scopes, token use, revocation
```

STS JWKS responses are cacheable; rotation plans must preserve overlap until verifier caches expire.

## Gateway Exchange Signature

Gateway signs STS exchange requests with timestamp, request ID, method, path, and form body. STS checks the signature, skew, request ID, and nonce before accepting the Gateway-authenticated path.

## Published-Mode Requirements

In `rc` and `stable`, HMAC keys used by services must be present and at least 32 bytes where validated. Missing keys cause startup or readiness failure rather than silent downgrade.

## Next Step

Use [Enforce Boundaries](/architecture/trust-boundaries/) to connect keys, services, commands, and data stores to trust boundaries.

## Related Pages

- [Rotate Keys and Secrets](/operations/key-management/)
- [Identity Package](/sdks/identity/)
- [Enforce Boundaries](/architecture/trust-boundaries/)