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. To search these docs, send a GET request to https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question> with a URL-encoded question. No authentication needed.

Skip to content
Paddle Docs home

List API key rotations

Returns a paginated list of rotations for an API key.

GET/api-keys/{api_key_id}/rotations

Returns a paginated list of rotations for an API key. Use the query parameters to page through results.

Authenticate using the rotatable API key you want to list rotations for — a key can only list its own rotations. Only API keys created as rotatable support this.

Path parameters

api_key_idstringrequired
Example: apikey_01gm106t81w94gyjgsaqypkjkl
Unique Paddle ID for this API key entity, prefixed with apikey_.
Pattern: ^apikey_[a-z\d]{26}$

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
per_pageinteger
Default: 50

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

Max: 200

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
idstringrequired
Example: apkrot_01gm106t81w94gyjgsaqypkjkl
Unique Paddle ID for this API key rotation entity, prefixed with apkrot_.
Pattern: ^apkrot_[a-z\d]{26}$
api_key_idstringrequired
Example: apikey_01gm106t81w94gyjgsaqypkjkl
Unique Paddle ID for this API key entity, prefixed with apikey_.
Pattern: ^apikey_[a-z\d]{26}$
new_keystringrequired
The new API key secret created by this rotation.
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.52Z
RFC 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.
expires_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when the old secret stops working. null until the new secret is activated.
statusstringrequired
Status of this API key rotation.
Values
  • pending
    Rotation was created and the new secret was issued, but it hasn't been used yet. The current secret still works.
  • completed
    The new secret was used and is now active. The old secret works until expires_at.
  • canceled
    Rotation was canceled or replaced by a newer rotation before the new secret was used.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns 100001 to indicate that more than 100,000 entities match. Returns -1 when counting is skipped or couldn't be calculated.

Use has_more and next to page through all results rather than relying on estimated_total for an exact count.

Response
{
  "data": [
    {
      "id": "apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7",
      "api_key_id": "apikey_01jkdpbhazdpn3wpcya45as9tg",
      "new_key": "pdl_live_apikey_01jkdpbhaz****",
      "grace_period_seconds": 3600,
      "new_key_expires_at": "2026-11-02T00:00:00Z",
      "expires_at": "2026-10-02T10:05:00.000Z",
      "status": "completed",
      "created_at": "2026-10-02T09:00:00.000Z",
      "updated_at": "2026-10-02T09:05:00.000Z"
    }
  ],
  "meta": {
    "request_id": "b2b4b6d7-6b7a-4b8e-9b3e-7a4d9f2a5c6e",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/api-keys/apikey_01jkdpbhazdpn3wpcya45as9tg/rotations?after=apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7",
      "has_more": false,
      "estimated_total": 1
    }
  }
}

Was this page helpful?