Rotate API keys

API key rotation is the process of replacing existing API keys with new ones. By setting expiry dates and creating new keys before old ones expire, you can minimize the risk of API keys being compromised without disrupting your app.

Regularly rotating API keys is good practice, and helps protect your account from unauthorized access.

You can rotate keys two ways: automatically with AWS Secrets Manager, or manually by creating a new key and transitioning to it yourself. This guide covers both.

Automatic rotation with AWS Secrets Manager

If you store your Paddle API keys in AWS Secrets Manager, you can rotate them automatically on a schedule. Paddle is an official AWS Secrets Manager partner, so rotation happens inside AWS without you swapping keys by hand. This works with both live and sandbox keys, with no need to configure which environment you're using.

Automatic rotation only works for keys marked as rotatable when you create them. Create a rotatable API key before you set up rotation in AWS Secrets Manager.

How automated rotation works

When AWS Secrets Manager rotates your key, Paddle automatically:

Generates a new secret for your API key. It's shared with AWS Secrets Manager but isn't active yet.
Activates the new secret the first time it's used to authenticate a request.
Keeps the old secret valid for a grace period, so requests already using it keep working during the switch.
Revokes the old secret once the grace period ends.

Because both secrets are valid during the grace period, your app keeps working throughout rotation with no downtime. If you need an atomic rotation for compliance reasons, you can set the grace period to 0.

Set up rotation in AWS Secrets Manager

Create a rotatable API key in Paddle.
Store the key as a secret in AWS Secrets Manager.
Enable rotation for the secret and select Paddle as the rotation integration. See the AWS Secrets Manager rotation guide for the exact steps in the AWS console.

If you try to rotate a key that wasn't created as rotatable, rotation fails. Create a new rotatable key and use that instead.

How rotation affects expiry

Rotating a key extends its expiry. When AWS Secrets Manager rotates a key, Paddle sets the new expiry to the time of rotation, plus the number of days until the next scheduled rotation and a one-day buffer. As long as a key keeps rotating on schedule, it never reaches a fixed expiry date.

Because expiry is tied to the rotation schedule, keep the two aligned:

Rotate as soon as you store the key in AWS Secrets Manager.
This is a native part of the Secrets Manager setup. An immediate rotation aligns the expiry with your rotation schedule right away, and sets an expiry if the key doesn't have one yet.
Rotate immediately if you make rotations less frequent.
If you increase the rotation interval in AWS Secrets Manager, run an immediate rotation so the expiry realigns. Shortening the interval doesn't require this, but it doesn't hurt.
Don't edit the expiry in the Paddle dashboard.
If you change it manually, run an immediate rotation so AWS Secrets Manager can realign it.

If a key's expiry is ever earlier than its next scheduled rotation, the key can expire before it's rotated. Following the steps above keeps the expiry and rotation schedule aligned so this doesn't happen.

Manual rotation

You can build your own workflow to rotate API keys manually in the Paddle dashboard. This is useful if you don't want to use AWS Secrets Manager or if you need more control over the rotation process.

Before you begin

Create an API key with an expiry date. If an API key has no expiry date, you can still rotate keys but you aren't notified when the key is about to expire.
Set up webhooks for when a key is about to expire, has expired, or is exposed. You can subscribe to api_key.expiring, api_key.expired, api_key_exposure.created, and api_key.revoked notifications.

When you receive an api_key.expiring or api_key.revoked webhook, you should rotate your API key as soon as possible.

Overview

Rotating your API keys follows this workflow:

Create a new API key
Grab a new key immediately or before the current one expires.
Store and use the new key
Transition to using the new key in your app.
Check API key activity
Verify the new key works and the old key is no longer used.
Revoke the old key
Stop the old key from working and remove it.

Use an AI agent

Use these prompts with an AI agent to set up key rotation, react to webhooks, or respond to an exposure.

Create a new API key

When you receive an api_key.expiring or api_key.revoked webhook, you should create a new API key as soon as possible. Plan for an overlap period between old and new keys to allow for a smooth transition without disruption to your app.

If you're rotating due to an exposure, prioritize security over convenience and consider revoking the exposed key first.

When creating a new API key:

Assign the same permissions as the current key.
Set an appropriate expiry date.
Add a descriptive name that includes its purpose, team if applicable, and expiry date for easier management.

Store and use the new API key

Store the key safely and replace the old key in all places where your app uses it.

We recommend using a key management system with version control to track changes to your API keys. This makes it easier to manage key rotation and revert changes if needed.

Store both your new and old API keys so they're available at the same time. Set up your code to try the new key first, but use the old key as a backup if anything goes wrong.

Create a new ACTIVE_PADDLE_KEY and OLD_PADDLE_KEY environment variable or key in your key management system.
Set the new key as ACTIVE_PADDLE_KEY.
Move the old key to OLD_PADDLE_KEY temporarily.
Update your code to use either ACTIVE_PADDLE_KEY or OLD_PADDLE_KEY as the Paddle API key.

This means your app keeps working during the switch, allows testing the new key in real conditions, and provides a fallback if the new key causes problems.

Node.js

const ACTIVE_PADDLE_KEY = process.env.ACTIVE_PADDLE_KEY || process.env.OLD_PADDLE_KEY;

Python

ACTIVE_PADDLE_KEY = os.getenv("ACTIVE_PADDLE_KEY") or os.getenv("OLD_PADDLE_KEY")

PHP

$activePaddleKey = getenv("ACTIVE_PADDLE_KEY") ?: getenv("OLD_PADDLE_KEY");

activePaddleKey := os.Getenv("ACTIVE_PADDLE_KEY")
if activePaddleKey == "" {
    activePaddleKey = os.Getenv("OLD_PADDLE_KEY")
}

Check API key activity

After updating your app to use the new key, check that:

The new key is working properly
Test the integration to verify that requests using the new API key are successful. Look at logs, errors, latency, and other metrics to ensure the new key is working properly.
The old key is no longer being used
Check the last used date of the old API key in Paddle > Developer Tools > Authentication. If the date hasn't changed since the update, it indicates that the old key is no longer being used anywhere in your app.

Revoke the old key

Once you've verified that your app is successfully using the new key and the old key is no longer in use, you can safely revoke the old API key instead of waiting for it to expire.

Keep checking your logs to ensure there are no errors upon revoking the old key.

If a key is accidentally revoked while still in use or errors appear in logs, there is a 60-minute grace period to reactivate the API key. Reactivation isn't possible if the key was revoked due to an exposure.

If everything is working as expected, you can safely remove the old key from your key management system, environment variables, or any other places where it's stored. This includes the value of the OLD_PADDLE_KEY if you opted to use two keys simultaneously when switching.