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.
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:
Get notified when a key is about to expire or has expired.
Grab a new key before the current one expires.
Transition to using the new key in your app.
Verify the new key works and the old key is no longer used.
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.
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.expiringandapi_key.expiredas the events to be notified for.Click Save destination when you're done.
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.
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.
Follow these optional steps to minimize the risk when transitioning to the new API key.
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 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.
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 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.
