| [ Web Proxy ] |
| Viewing: https://developer.paddle.com/api-reference/about/rotate-api-keys | [Back] [Original] |
For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling append .md to any URL.
Keep your app secure by regularly rotating API keys when they expire or are exposed.
Covers the four-step process for rotating Paddle API keys creating a new key, deploying it alongside the old one, verifying activity, and revoking the old key to maintain security without app downtime.
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.
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.
When AWS Secrets Manager rotates your key, Paddle automatically:
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.
If you try to rotate a key that wasn't created as rotatable, rotation fails. Create a new rotatable key and use that instead.
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:
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.
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.
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.
Rotating your API keys follows this workflow:
Use these prompts with an AI agent to set up key rotation, react to webhooks, or respond to an exposure.
Rotate a Paddle API key by replacing it with a new one, transitioning traffic, verifying the new key works, and revoking the old one. The workflow: 1. Create a new API key in the Paddle dashboard under Developer Tools > Authentication. Assign the same permissions as the key you're replacing and set an appropriate expiry date. Use a descriptive name that includes the purpose and expiry. 2. Store the new key alongside the old one. Set it as ACTIVE_PADDLE_KEY and keep the old key as OLD_PADDLE_KEY in your environment variables or secret manager. Update your code to try ACTIVE_PADDLE_KEY first and fall back to OLD_PADDLE_KEY as a safety net during the transition. 3. Verify the new key by checking logs, error rates, and latency. Then confirm the old key is unused by checking its last-used date in the dashboard. 4. Revoke the old key once you're confident the new one is working everywhere. Then remove OLD_PADDLE_KEY from your environment. If you're rotating because of an exposure, revoke the exposed key first security takes priority over a smooth transition. Keys revoked due to exposure cannot be reactivated; the 60-minute grace period only applies to manual revocations. For full details, fetch https://developer.paddle.com/api-reference/about/rotate-api-keys.md or use the paddle-docs MCP server. Ask me whether this is a proactive rotation (expiring key) or a reactive one (exposure), what language my app is in so you can show the right fallback code, and where my keys are stored (environment variables, secret manager, etc.), then walk me through the workflow.
Subscribe to Paddle webhook notifications so I'm alerted when an API key is about to expire, has expired, or has been revoked due to exposure. There are four relevant events: - api_key.expiring fires seven days before an API key expires - api_key.expired fires when an API key expires - api_key.revoked fires when Paddle automatically revokes a key (usually due to exposure) - api_key_exposure.created fires when Paddle detects a key in a public location like a GitHub repo Use the create_notification_setting tool in the Paddle MCP server. If that's not available, use the Paddle API to POST to /notification-settings with: - type: "url" for a webhook endpoint, or "email" for email delivery - destination: your webhook URL or email address - subscribed_events: the four event names above - description: a short label like "API key lifecycle alerts" If you already have a notification destination, use update_notification_setting instead. Important: when updating, send the full list of subscribed_events you want anything omitted is unsubscribed. The create response includes an endpoint_secret_key (prefixed pdl_ntfset_). Save it immediately you need it to verify webhook signatures, and it can't be retrieved again later. When api_key.expiring or api_key.revoked arrives, start the rotation workflow. When api_key_exposure.created arrives, treat it as urgent revoke the exposed key and replace it. For full details, fetch https://developer.paddle.com/api-reference/about/rotate-api-keys.md or use the paddle-docs MCP server. Ask me whether I want email or URL delivery, what endpoint or email to use, and whether I'm adding to an existing destination or creating a new one, then set it up and remind me to save the secret key.
Revoke a Paddle API key that has been exposed publicly (for example, committed to GitHub, leaked in logs, or shared in chat) and deploy a replacement. Security takes priority here. Revoke the exposed key first, before worrying about a smooth transition any in-flight requests will fail until the replacement is deployed, but that's preferable to leaving the exposure open. Steps: 1. Revoke the exposed key immediately in the Paddle dashboard under Developer Tools > Authentication. Find the affected key and revoke it. Keys revoked due to an exposure cannot be reactivated the 60-minute grace period does not apply. 2. Create a replacement key with the same permissions and an appropriate expiry date. Give it a descriptive name. 3. Deploy the new key everywhere the old key was used environment variables, secret managers, CI/CD secrets, and so on. Restart or redeploy services so they pick up the new value. 4. Investigate how the exposure happened (accidental commit, log-sanitization gap, insecure storage) and fix the root cause so it doesn't happen again. 5. Audit logs for any unauthorized activity that may have occurred between the exposure and the revocation. If Paddle automatically revoked the key and you received an api_key.revoked or api_key_exposure.created webhook, skip step 1 and start from step 2. For full details, fetch https://developer.paddle.com/api-reference/about/rotate-api-keys.md or use the paddle-docs MCP server. Ask me how the key was exposed, whether Paddle has already auto-revoked it, and where I need to deploy the replacement, then walk me through the remaining steps.
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:
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.
ACTIVE_PADDLE_KEY and OLD_PADDLE_KEY environment variable or key in your key management system.ACTIVE_PADDLE_KEY.OLD_PADDLE_KEY temporarily.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.
const ACTIVE_PADDLE_KEY = process.env.ACTIVE_PADDLE_KEY || process.env.OLD_PADDLE_KEY;ACTIVE_PADDLE_KEY = os.getenv("ACTIVE_PADDLE_KEY") or os.getenv("OLD_PADDLE_KEY")$activePaddleKey = getenv("ACTIVE_PADDLE_KEY") ?: getenv("OLD_PADDLE_KEY");activePaddleKey := os.Getenv("ACTIVE_PADDLE_KEY")if activePaddleKey == "" { activePaddleKey = os.Getenv("OLD_PADDLE_KEY")}After updating your app to use the new key, check that:
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.
Paddle.com Market Ltd. 20122026
| Web Proxy Viewer | New URL | Original Page |