Docs

Rotate API keys

Keep your app secure by regularly rotating API keys when they expire or are exposed.

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.

Before you begin

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:

  1. Create a new API key
    Grab a new key immediately or before the current one expires.
  2. Store and use the new key
    Transition to using the new key in your app.
  3. Check API key activity
    Verify the new key works and the old key is no longer used.
  4. 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.

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.

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.

  1. Create a new ACTIVE_PADDLE_KEY and OLD_PADDLE_KEY environment variable or key in your key management system.
  2. Set the new key as ACTIVE_PADDLE_KEY.
  3. Move the old key to OLD_PADDLE_KEY temporarily.
  4. 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");
Go
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 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.

Was this page helpful?