Master Key Rotation

The master key is the key-encryption key (KEK) for envelope encryption in a self-hosted AISIX Enterprise control plane. It wraps the per-row data-encryption keys that protect secrets at rest — provider upstream credentials, guardrail provider credentials, and the root certificate authority's private key. On-Premises Configuration already documents the two settings that hold it, AISIX_CLOUD_MASTER_KEY and AISIX_CLOUD_MASTER_KEY_ID, and warns against changing the key value without a rotation procedure. This page is that procedure.

This page applies to On-Premises. On Hybrid Cloud, API7 operates the control plane and its master key as part of the hosted service.

Why Rotate

Rotate the master key for the same reasons you rotate any long-lived encryption key:

• Scheduled rotation under an annual or other periodic security policy.
• Post-incident response when the key may have been exposed — through logs, backups, container introspection, or a departed operator who had production access.
• Moving the key to a different storage mechanism, such as from a plain environment variable to a secret manager or KMS-backed value.

How Rotation Works

The control plane holds a key ring rather than a single key: one active key, used to encrypt every new value going forward, and zero or more retired keys, used only to decrypt values that were encrypted under them. Every encrypted row persists the identifier of the key that wrapped it, so on read the control plane looks up the matching ring entry regardless of whether it is the active key or a retired one.

This means introducing a new active key and retiring the old one is a configuration change, not a data migration: existing rows keep decrypting correctly through the retired key entry while every new write uses the new active key. There is no downtime and no requirement to re-encrypt historical rows immediately.

Rotate the Master Key

1. Generate a New Key and Choose Its Identifier

Generate a new 32-byte key and base64-encode it:

openssl rand -base64 32

Choose an identifier for it. AISIX_CLOUD_MASTER_KEY_ID must match ^[a-z0-9:-]+$ — lowercase letters, digits, :, and - only. A namespaced value such as env:2026-q2 keeps successive rotations easy to tell apart; avoid uppercase letters, underscores, or other delimiters, which the control plane rejects at startup rather than accepting and misreading later.

2. Introduce the New Key and Retire the Old One

For the Docker Compose package, update ./aisix-self-hosted/.env: set AISIX_CLOUD_MASTER_KEY to the new key value and AISIX_CLOUD_MASTER_KEY_ID to its new identifier, and add the previous key as a retired entry under the naming pattern AISIX_CLOUD_MASTER_KEY_RETIRED_<safe_id>, where <safe_id> is the previous key's identifier with : written as _ (for example, retiring env:2026-q1 becomes the variable AISIX_CLOUD_MASTER_KEY_RETIRED_env_2026-q1, set to that key's base64 value):

# New active key
AISIX_CLOUD_MASTER_KEY=<new-key-base64>
AISIX_CLOUD_MASTER_KEY_ID=env:2026-q2

# Previous key, retained for decrypt-only
AISIX_CLOUD_MASTER_KEY_RETIRED_env_2026-q1=<previous-key-base64>

For the Helm chart, apply the equivalent change to secrets.masterKey and secrets.masterKeyID, and consult your current package version's chart documentation or your support contact for the retired-key value name — the chart's values.yaml may expose this differently than the Compose .env naming shown above, and this page does not assume that mapping is identical across package versions.

Confirm the exact current variable naming for your installed version against On-Premises Configuration before editing a production .env file, since that reference is the authoritative, version-specific source and this page's example may lag a package update.

Recreate the control-plane services (cp-api and dp-manager together — both must hold the same ring) so the new configuration takes effect:

docker compose up -d --wait api dpm

On the Helm chart, this is the normal helm upgrade you already use for other configuration changes; see On-Premises Installation.

3. Confirm Both Processes Agree

cp-api and dp-manager are peers that must share the identical key ring. After recreating both, check their startup logs for the active key identifier they report. If the two processes disagree — one still reports the old active identifier, or they report the same identifier but were configured with different key bytes — cross-process operations that rely on the shared key will fail at the first attempt to decrypt a value the other process wrote. Confirm both processes were recreated with the same updated configuration before considering rotation complete.

4. Decide Whether to Re-Wrap Historical Rows

At this point, existing secrets remain readable through the retired key entry, and new writes use the new active key. You can leave the deployment in this mixed state indefinitely — reading a retired-key row costs no more than reading an active-key row, since the lookup is a key-identifier match, not a broader operation.

If your rotation policy requires retiring the old key value entirely (removing it from configuration, not just from active use), every row still wrapped under it must first be re-encrypted under the new key. This re-wrap only touches the small wrapped data-encryption key stored per row — the underlying business secret is byte-identical before and after — but it requires an operation the AISIX Enterprise Admin API does not currently expose as a self-service endpoint. Contact API7 support to re-wrap historical rows before removing a retired key from your configuration.

5. Remove the Retired Key

Once every row that was wrapped under the retired key has been re-encrypted under the current active key, remove the retired-key configuration and recreate the control-plane services again. The old key value can then be safely and irrecoverably discarded.

Rehearse Before You Need It

Rotating in a non-production environment first, on the same package version and topology you run in production, is the cheapest way to confirm your rotation steps actually work before an incident forces the pace. Pair this with the recovery rehearsal in Organization Data Export and Import, which already recommends exporting a full bundle — encrypted under the current master key — before every control-plane upgrade.

Next Steps

• On-Premises Configuration — the AISIX_CLOUD_MASTER_KEY and AISIX_CLOUD_MASTER_KEY_ID settings this page rotates.
• Organization Data Export and Import — export and import behavior when master keys differ between a source and target deployment.
• Backup and Restore — the database backup that also protects the encrypted secrets this page's key wraps.