Rotate API keys

Schedule API keys to expire and rotate them at regular intervals to ensure your app remains secure.

Regularly rotating API keys is a security best practice that helps protect accounts from unauthorized access. 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.

How it works

API keys can be created with an expiry date. Once an API key expires, it can no longer be used to authenticate requests to the Paddle API.

This encourages you to change your keys at a regular interval. API key rotation is the process of replacing those existing API keys with new ones.

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.

We strongly recommend setting an expiry date for your API keys. API keys can be used to access sensitive data and should be rotated regularly.

It's still good practice to regularly check your API keys in Paddle > Developer tools > Authentication and ensure none are approaching their expiry date without a replacement being prepared.

Overview

Rotating your API keys follows this workflow:

Set up notifications
Get notified when a key is about to expire or has expired.
Create a new API key
Grab a new key 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.

1. Set up notifications

You can get notified when a key is about to expire or has expired by subscribing to webhook or email notifications. An API key must have an expiry date set to receive notifications.

Subscribe to the api_key.expiring notification, and optionally to the api_key.expired as a safety net.

The api_key.expiring notification is always sent seven days before the API key expires.

Webhook

Go to Paddle > Developer tools > Notifications.
Click New destination.
Select Email as the notification type and enter your email address under Email.
Select api_key.expiring and api_key.expired as the events to be notified for.
Click Save destination when you're done.

Illustration of the notifications screen in Paddle. It shows the email destination form. There's a field to enter the email address to be notified at. There's a button that says Save.

2. Create a new API key

Create a new API key as soon as possible. Plan for an overlap period between old and new keys. This allows 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

API keys can't be created and rotated programmatically. New keys must be manually created in the dashboard and updated in your app.

3. Store and use the new API key

API keys are only visible once upon creation.

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.

Follow these optional steps to minimize the risk when transitioning to the new API key.

Verify your new key works

Use old and new keys simultaneously

4. 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 for 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.

5. 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.

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.

Manage API keys

Permissions

Authentication