---
title: "Configure Secret Backends"
url: "https://docs.caracal.run/v1.0/operations/secret-backends/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/operations/secret-backends.md"
description: "Select and verify the implemented backend for user-entered credential envelopes."
page_type: "workflow"
concepts: []
requires: []
---

# Configure Secret Backends

Canonical URL: https://docs.caracal.run/v1.0/operations/secret-backends/
Markdown URL: https://docs.caracal.run/markdown/v1.0/operations/secret-backends.md
Description: Select and verify the implemented backend for user-entered credential envelopes.
Page type: workflow
Concepts: none
Requires: none

---

`CARACAL_SECRET_BACKEND` selects storage for user-entered credentials. It does not replace runtime secret delivery. Values are envelope-encrypted under `SECRET_STORE_KEK` before backend storage.

## Choose a Backend

Implemented identifiers are `builtin`, `vault`, `infisical`, `azurekeyvault`, `awssecretsmanager`, `gcpsecretmanager`, and `custom`. `builtin` stores envelopes in Postgres. External backends require their documented endpoint, identity, project/region, or token variables on API and STS.

## Safe Procedure

1. Back up Postgres, runtime secrets, and external backend data.
2. Configure one backend on API and STS with the same KEK.
3. Restart API and STS; wait for readiness.
4. Create a disposable provider credential and perform a token exchange.
5. Verify backend operation/error metrics and delete the disposable object.

STS caches external reads for 60 seconds and may serve stale cached data for up to 10 minutes during errors. It never falls back to another backend.

## KEK Rotation

Deploy the replacement as `SECRET_STORE_KEK` and retiring value as `SECRET_STORE_KEK_PREVIOUS`. Run `node apps/api/scripts/rotate-secret-store-kek.mjs` from a checkout with the API service's environment (the script ships beside the API service), verify zero failures, then remove the previous key and restart API and STS.

:::danger[Permanent credential loss]
Removing the retiring KEK before all envelopes are re-sealed makes remaining envelopes unreadable.
:::

## Backend Migration and Recovery

Use `node apps/api/scripts/migrate-secret-backend.mjs <target-kind>` from the same environment while the source remains configured. Switch services only after copying succeeds. On failure, keep the source selected and rerun; do not create a fallback chain.

## Next Step

Plan dependent rotations in [Rotate Keys and Secrets](/v1.0/operations/key-management/).