Rotating an API key replaces its secret. The key keeps its ID, name, and permissions, so there's nothing to reconfigure in Paddle. The old secret keeps working for a grace period while you switch over.
Rotating keys regularly limits how long a leaked secret stays useful. You can rotate keys from your own tooling using the Paddle API, or on a schedule with AWS Secrets Manager.
How it works
Every rotation follows the same steps, whether you start it using the Paddle API or AWS Secrets Manager starts it for you:
- Paddle issues a new secret. The rotation has a status of
pending, and the current secret keeps working for as long as the new one goes unused. - The first request with the new secret activates it. The rotation status changes to
completed. You don't need to make a separate request to complete a rotation. - The old secret keeps working for a grace period. The grace period starts when the new secret is activated, not when you create the rotation. It's between
0and86400seconds (24 hours). Set it to0for an atomic rotation, where the old secret stops working as soon as the new one is used. - The old secret stops working.
expires_aton the rotation tells you when.
Both secrets work during the grace period, so requests that still use the old secret keep working while you roll out the new one.
| Status | Description |
|---|---|
pending | The new secret was created but hasn't been used yet. The current secret still works. |
completed | The new secret is active. The old secret works until expires_at. |
canceled | The rotation was canceled before the new secret was used, for example because a newer rotation replaced it. |
A pending rotation doesn't expire. The current secret keeps working until the new one is used, however long that takes. A key can only have one pending rotation at a time, and creating a new rotation cancels any pending one, so only the latest secret can be activated.
How rotation affects expiry
A rotation can also change the key's expiry date. Paddle applies the new expiry when the new secret is activated:
- With the Paddle API, pass
new_key_expires_atwhen you create the rotation. If you leave it out, the key keeps its current expiry. - With AWS Secrets Manager, Paddle sets the new expiry for you: 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.
The api_key.expiring and api_key.expired notifications follow the new expiry.
Before you begin
- Create a rotatable API key. You can only rotate keys that had Rotatable turned on when they were created, and you can't turn it on later. Create a rotatable API key in Paddle > My account > Settings > Authentication.
- Set an expiry date. You can rotate a key without an expiry date, but you won't get
api_key.expiringreminders to rotate it. - Subscribe to API key webhooks.
api_key.expiringandapi_key.expiredtell you when to rotate.api_key_exposure.createdandapi_key.revokedtell you when a key is exposed or revoked.api_key_rotation.createdandapi_key_rotation.updatedlet you track rotations and spot ones you didn't start yourself.
Replace a key that isn't rotatable
You can't rotate legacy keys, keys created before rotation was available, or keys created without Rotatable turned on. Replace them with a rotatable key once, then rotate that key from then on:
- Create a new API key with Rotatable turned on, the same permissions as the current key, and an expiry date.
- Replace the old key everywhere your app uses it.
- Check that the old key is no longer used. Its last used date is in Paddle > My account > Settings > Authentication. You can also get the API key using another key with the
api_key.readpermission and checklast_used_at. It's accurate to within an hour, so wait at least an hour after the switch before you rely on it. - Revoke the old key.
Revoked keys can't be rotated either, so replace a revoked key with a new one.
If a key was exposed, revoke it first, then replace it. If you revoke a key by mistake, you have 60 minutes to reactivate it. Keys revoked because of an exposure can't be reactivated.
Use an AI agent
Use these prompts with an AI agent to set up key rotation, react to webhooks, or respond to an exposure.
Rotate using the Paddle API
Use the Paddle API to rotate a key from your own tooling, like a secrets manager, a scheduled job, or a CI pipeline.
Authenticate with the key you're rotating
Authenticate requests with the key that you're rotating. A key doesn't need any permissions to rotate itself, but it can't rotate other keys on your account. If the API key ID in the path isn't the key that you're authenticating with, Paddle returns a 403 with the error code forbidden.
You need the API key ID for the request path. It's apikey_ followed by the 26-character string that comes after pdl_live_apikey_ or pdl_sdbx_apikey_ in the key. You can also copy it from Paddle > My account > Settings > Authentication.
Sandbox API keys contain _sdbx. Sandbox and live keys are separate — using one against the other API returns a forbidden error.
Create a rotation
Send a POST request to the /api-keys/{api_key_id}/rotations endpoint to create a rotation.
In your request, include:
grace_period_seconds: How long the old secret keeps working after the new secret is activated, in seconds. Between0and86400(24 hours).new_key_expires_at: Optional. Sets when the key expires after this rotation, as an RFC 3339 timestamp. Paddle applies it when the new secret is activated. If omitted, the key keeps its current expiry.
If successful, Paddle returns the new rotation. new_key holds the new secret.
{ "grace_period_seconds": 3600, "new_key_expires_at": "2027-02-01T00:00:00Z"}{ "data": { "id": "apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7", "api_key_id": "apikey_01gtgztp8f4kek3yd4g1wrksa3", "new_key": "pdl_sdbx_apikey_01gtgztp8f4kek3yd4g1wrksa3_Zr8kQ2mNw4pLx7VbT9cYhD_K3P", "grace_period_seconds": 3600, "new_key_expires_at": "2027-02-01T00:00:00Z", "expires_at": null, "status": "pending", "created_at": "2026-11-09T09:00:00.000Z", "updated_at": "2026-11-09T09:00:00.000Z" }, "meta": { "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }}expires_at is when the grace period ends and the old secret stops working. It's null until the new secret is activated.
Store new_key before you do anything else. Paddle doesn't return the full secret again. If you lose it before it's activated, create a new rotation. The new rotation cancels the pending one.
If you rotate on a schedule, pass new_key_expires_at on every rotation and set it to the next rotation date plus a buffer, like a day. Otherwise the key keeps its current expiry and can expire between rotations.
Switch to the new secret
Replace the old secret with new_key everywhere your app uses the key. The first request that authenticates with the new secret activates it and starts the grace period.
Choose a grace period that's long enough to roll the new secret out everywhere. Requests that still use the old secret keep working until expires_at. After that, they fail.
Check that the rotation completed
Send a GET request to the /api-keys/{api_key_id}/rotations endpoint to list rotations for a key. To get a single rotation, use /api-keys/{api_key_id}/rotations/{rotation_id}.
Authenticate with the key that the rotations belong to.
If successful, Paddle returns the key's rotations. Once the new secret is in use, the rotation status is completed, and expires_at shows when the old secret stops working.
new_key is obfuscated in this response, and the visible part is the same for every rotation of this key. To check which rotation is active, look at status and expires_at.
{ "data": [ { "id": "apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7", "api_key_id": "apikey_01gtgztp8f4kek3yd4g1wrksa3", "new_key": "pdl_sdbx_apikey_01gtgztp8f****", "grace_period_seconds": 3600, "new_key_expires_at": "2027-02-01T00:00:00Z", "expires_at": "2026-11-09T10:05:00.000Z", "status": "completed", "created_at": "2026-11-09T09:00:00.000Z", "updated_at": "2026-11-09T09:05:00.000Z" } ], "meta": { "request_id": "b2b4b6d7-6b7a-4b8e-9b3e-7a4d9f2a5c6e", "pagination": { "per_page": 50, "next": "https://sandbox-api.paddle.com/api-keys/apikey_01gtgztp8f4kek3yd4g1wrksa3/rotations?after=apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7", "has_more": false, "estimated_total": 1 } }}To get notified when a rotation completes instead of polling, subscribe to api_key_rotation.updated.
Automatic rotation with AWS Secrets Manager
If you store your Paddle API keys in AWS Secrets Manager, you can rotate them on a schedule. Paddle is an official AWS Secrets Manager partner, so rotation happens inside AWS and you don't swap keys by hand. It works with live and sandbox keys, and you don't need to say which account a key belongs to.
Rotations follow the same steps as with the Paddle API. AWS Secrets Manager gets the new secret from Paddle and starts using it, and the old secret keeps working for the grace period.
Don't rotate a key using the Paddle API if AWS Secrets Manager rotates it. If you activate a secret that AWS Secrets Manager doesn't have, the secret it stores stops working when the grace period ends.
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. Replace it with a rotatable key and use that instead.
Keep expiry aligned with your rotation schedule
AWS Secrets Manager sets the key's expiry from your rotation schedule, so keep the two aligned:
- Rotate as soon as you store the key in AWS Secrets Manager.
AWS Secrets Manager offers this when you set up rotation. An immediate rotation aligns the expiry with your schedule, 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. You don't need to do this if you shorten the interval.
If a key's expiry is earlier than its next scheduled rotation, the key can expire before it's rotated. Follow the preceding steps to keep them aligned.
Common errors
api_key_cannot_be_rotated |
| Returned when you try to rotate a key that wasn't created as rotatable. |