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

Get an API key rotation

Returns a rotation for an API key.

GET/api-keys/{api_key_id}/rotations/{rotation_id}

Returns a rotation for an API key.

Authenticate using the rotatable API key the rotation belongs to — a key can only fetch 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}$
rotation_idstringrequired
Example: apkrot_01gm106t81w94gyjgsaqypkjkl
Unique Paddle ID for this API key rotation entity, prefixed with apkrot_.
Pattern: ^apkrot_[a-z\d]{26}$

Response (200)

dataobjectrequired
Represents an API key rotation entity.
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.
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"
  }
}

Was this page helpful?