Appearance

Key Rotation Runbook ​

ZedGi gives every account a per-account X25519 keypair. The public key encrypts your database credentials client-side; the wrapped private key lives server-side (AES-256-GCM wrapped with the Master KEK) and is only ever used transiently on the gateway. Rotating the keypair invalidates old credential blobs without touching your API keys.

When to rotate ​

  • A machine that held an encrypted x-zedgi-cred blob may have been compromised.
  • Routine hygiene (e.g. quarterly).
  • After offboarding someone who had access to your deployment config.

API keys (zk_* identifier + signing secret) are not affected by key rotation. Those are rotated separately from the dashboard.

Rotate ​

Dashboard → Encryption Keys → Rotate, or:

http
POST /api/account/keys/rotate
Cookie: <dashboard session>

What happens:

  1. A new active keypair (key_version + 1) is generated; the previous key is marked retired.
  2. A security email is sent to the account owner.
  3. New x-zedgi-cred blobs must be encrypted with the new public key.

Update your clients ​

  1. Fetch the new public key — automatic if your SDK uses auto-pull (omit publicKey), or:
    http
    GET /api/account/keys/current
x-zedgi-key: zk_live_...
    Response now includes id (the account id used as the blob header), key_version, and public_key.
  2. If you pin keys manually, update publicKey, accountId, and keyVersion in your client config (or just re-create the client).
  3. Deploy.

Auto-pull SDKs ​

When the SDK is configured without a pinned publicKey, it caches the current key on first use. On a 412 response (a blob encrypted with a retired key), the SDK drops its cache, re-pulls the current key, and the next call re-encrypts automatically — so a redeploy is usually enough.

Grace window ​

Retired key versions keep working for a short grace window so in-flight deployments don't break, then are rejected. Plan to redeploy clients promptly after rotating.