Key Rotation

apikee supports two distinct types of rotation: rotating the signing secrets used to create keys, and rotating individual API keys issued to customers.

Rotating signing secrets

Signing secrets are the server-side strings used to create and verify key signatures. You rotate these when a secret is compromised or as a routine security practice.

Because the secrets config accepts an array, you can have multiple valid secrets simultaneously. Keys signed with any secret in the array will validate.

Add the new secret at index 0

# Before rotation
apikee = Apikee(secrets=["secret-v1"])

# After: new keys signed with secret-v2, old keys still verify against secret-v1
apikee = Apikee(secrets=["secret-v2", "secret-v1"])

Deploy the updated config

All instances of your app now use secret-v2 for new keys. Old keys signed with secret-v1 still validate because it remains in the array.

Wait for all v1 keys to expire

Keys contain their expiry timestamp (exp). Once all keys signed with secret-v1 have passed their expiry, they will be rejected naturally.

Remove the old secret

apikee = Apikee(secrets=["secret-v2"])

If you need to invalidate all keys signed with the old secret immediately (e.g. after a breach), remove secret-v1 from the array at step 2. This forces all existing keys to fail signature verification, which will reject them even before their exp timestamp.

Per-ecosystem config examples

apikee = Apikee(secrets=["secret-v2", "secret-v1"])

const apikee = new Apikee({ secrets: ['secret-v2', 'secret-v1'] })

apikee:
  secrets:
    - secret-v2
    - secret-v1

{ "Apikee": { "Secrets": ["secret-v2", "secret-v1"] } }

Rotating customer API keys

Individual customer keys can be rotated without disrupting their traffic.

Issue a new key to the customer

new_key = apikee.create(
    tenant="acme-corp",
    scopes=["read", "write"],
    expires_in=timedelta(days=90),
)
# Deliver to the customer securely

Customer migrates to the new key

During the migration window, both the old and new key are valid (as long as neither has expired).

Revoke the old key (optional)

If the old key still has time before its natural expiry and you want to invalidate it early:

Via dashboard: navigate to the client on apikee.dev and delete the old key
Via API: DELETE /client/{uuid}?keyId={keyId}

`autoRotate` flag

When creating a key, set autoRotate: true to have the platform automatically issue a replacement key before the current one expires. The new key is available in the dashboard and via webhook before the old key expires.

key = apikee.create(
    tenant="acme-corp",
    auto_rotate=True,      # platform will renew before expiry
)

Recommended rotation schedule

Secret type	Rotation frequency
Signing secret	Every 6–12 months, or immediately on suspected compromise
Customer API keys	At natural expiry (90d default), or on customer request
apikee.dev project key (`sk_live_`)	Every 90 days or on staff changes

Key Rotation

On this page