POST
/api-keys/{api_key_id}/rotationsCreates a rotation for an API key. Paddle generates a new secret for the key and returns it in new_key. The current secret keeps working. The new secret is activated the first time it's used to authenticate a request; the old secret then keeps working for grace_period_seconds before it stops working. Creating a rotation cancels any pending rotation for the same key.
Authenticate using the rotatable API key you want to rotate — a key can only rotate itself. Only API keys created as rotatable support this.
Path parameters
api_key_idstringrequired
Example:
apikey_01gm106t81w94gyjgsaqypkjklUnique Paddle ID for this API key entity, prefixed with
apikey_.Pattern:
^apikey_[a-z\d]{26}$Request body
grace_period_secondsintegerrequired
How long, in seconds, the old secret keeps working after the new secret is activated. The new secret is activated the first time it's used to authenticate a request. Set to
0 to stop the old secret working as soon as the new one is activated.Range: 0–86400
new_key_expires_atstring (date-time)
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the API key should expire after this rotation. Applied when the new secret is activated. If omitted, the API key keeps its current expiry.
Response (201)
dataobjectrequired
Represents an API key rotation entity when created.
idstringrequired
Example:
apkrot_01gm106t81w94gyjgsaqypkjklUnique Paddle ID for this API key rotation entity, prefixed with
apkrot_.Pattern:
^apkrot_[a-z\d]{26}$grace_period_secondsintegerrequired
How long, in seconds, the old secret keeps working after the new secret is activated. The new secret is activated the first time it's used to authenticate a request. Set to
0 to stop the old secret working as soon as the new one is activated.Range: 0–86400
new_key_expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the API key should expire after this rotation. Applied when the new secret is activated. If omitted, the API key keeps its current expiry.
api_key_idstringrequired
Example:
apikey_01gm106t81w94gyjgsaqypkjklUnique Paddle ID for this API key entity, prefixed with
apikey_.Pattern:
^apikey_[a-z\d]{26}$expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the old secret stops working.
null until the new secret is activated.created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
new_keystringrequired
The new API key, prefixed with
pdl_ and containing _apikey_. Store it securely and only share with services or apps you trust. You can't retrieve it again. Once the new key is used, it becomes the primary key, and the old key will continue to work until the grace period expires.Pattern:
^pdl_(live|sdbx)_apikey_[a-z\d]{26}_[a-zA-Z\d]{22}_[a-zA-Z\d]{3}$statusstringrequired
Default:
pendingStatus of this API key rotation.
Values
pendingRotation was created and the new secret was issued, but it hasn't been used yet. The current secret still works.completedThe new secret was used and is now active. The old secret works untilexpires_at.canceledRotation was canceled or replaced by a newer rotation before the new secret was used.
metaobjectrequired
Information about this response.
request_idstringrequired
Example:
b15ec92e-8688-40d4-a04d-f44cbec93355Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
{ "grace_period_seconds": 3600, "new_key_expires_at": "2026-11-02T00:00:00Z"}{ "data": { "id": "apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7", "api_key_id": "apikey_01jkdpbhazdpn3wpcya45as9tg", "new_key": "pdl_live_apikey_01jkdpbhazdpn3wpcya45as9tg_Wq4Hn7Kd2Lp9Vx3Tb6Mz8R_J5s", "grace_period_seconds": 3600, "new_key_expires_at": "2026-11-02T00:00:00Z", "expires_at": null, "status": "pending", "created_at": "2026-10-02T09:00:00.000Z", "updated_at": "2026-10-02T09:00:00.000Z" }, "meta": { "request_id": "b2b4b6d7-6b7a-4b8e-9b3e-7a4d9f2a5c6e" }}