> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> 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. It returns a JSON array of `{content, source_url}`, most relevant first.

# api_key_rotation.updated

Occurs when an API key rotation's status changes.

---

Occurs when the status of an [API key rotation](https://developer.paddle.com/api-reference/about/rotate-api-keys.md) changes:

- `completed` when the new secret authenticates a request for the first time. `expires_at` shows when the old secret stops working.
- `canceled` when a newer rotation replaces it before its new secret is used.

[`api_key_rotation.created`](https://developer.paddle.com/webhooks/api-keys/api-key-rotation-created.md) occurs when the rotation starts. If the rotation sets a new expiry date for the key, [`api_key.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-updated.md) also occurs when the rotation is completed.
## Schema

```json
{
  "type": "object",
  "required": [
    "event_id",
    "event_type",
    "occurred_at",
    "notification_id",
    "data"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "pattern": "^evt_[a-z\\d]{26}$",
      "description": "Unique Paddle ID for this event, prefixed with `evt_`.",
      "title": "Event ID",
      "examples": [
        "evt_01gks14ge726w50ch2tmaw2a1x"
      ]
    },
    "event_type": {
      "type": "string",
      "enum": [
        "address.created",
        "address.imported",
        "address.updated",
        "adjustment.created",
        "adjustment.updated",
        "api_key.created",
        "api_key.expired",
        "api_key.expiring",
        "api_key.revoked",
        "api_key.updated",
        "api_key_exposure.created",
        "api_key_rotation.created",
        "api_key_rotation.updated",
        "business.created",
        "business.imported",
        "business.updated",
        "client_token.created",
        "client_token.revoked",
        "client_token.updated",
        "customer.created",
        "customer.imported",
        "customer.updated",
        "discount.created",
        "discount.imported",
        "discount.updated",
        "discount_group.created",
        "discount_group.updated",
        "meter.created",
        "meter.updated",
        "payment_method.saved",
        "payment_method.deleted",
        "payout.created",
        "payout.paid",
        "price.created",
        "price.imported",
        "price.updated",
        "product.created",
        "product.imported",
        "product.updated",
        "report.created",
        "report.updated",
        "subscription.activated",
        "subscription.canceled",
        "subscription.created",
        "subscription.imported",
        "subscription.past_due",
        "subscription.paused",
        "subscription.resumed",
        "subscription.trialing",
        "subscription.updated",
        "transaction.billed",
        "transaction.canceled",
        "transaction.completed",
        "transaction.created",
        "transaction.paid",
        "transaction.past_due",
        "transaction.payment_failed",
        "transaction.ready",
        "transaction.revised",
        "transaction.updated",
        "usage_balance.depleted"
      ],
      "description": "Type of event sent by Paddle, in the format `entity.event_type`.",
      "title": "Event type name",
      "x-enum-descriptions": {
        "address.created": {
          "description": "An [`address.created`](https://developer.paddle.com/webhooks/addresses/address-created) event."
        },
        "address.imported": {
          "description": "An [`address.imported`](https://developer.paddle.com/webhooks/addresses/address-imported) event."
        },
        "address.updated": {
          "description": "An [`address.updated`](https://developer.paddle.com/webhooks/addresses/address-updated) event."
        },
        "adjustment.created": {
          "description": "An [`adjustment.created`](https://developer.paddle.com/webhooks/adjustments/adjustment-created) event."
        },
        "adjustment.updated": {
          "description": "An [`adjustment.updated`](https://developer.paddle.com/webhooks/adjustments/adjustment-updated) event."
        },
        "api_key.created": {
          "description": "An [`api_key.created`](https://developer.paddle.com/webhooks/api-keys/api-key-created) event."
        },
        "api_key.expired": {
          "description": "An [`api_key.expired`](https://developer.paddle.com/webhooks/api-keys/api-key-expired) event."
        },
        "api_key.expiring": {
          "description": "An [`api_key.expiring`](https://developer.paddle.com/webhooks/api-keys/api-key-expiring) event."
        },
        "api_key.revoked": {
          "description": "An [`api_key.revoked`](https://developer.paddle.com/webhooks/api-keys/api-key-revoked) event."
        },
        "api_key.updated": {
          "description": "An [`api_key.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-updated) event."
        },
        "api_key_exposure.created": {
          "description": "An [`api_key_exposure.created`](https://developer.paddle.com/webhooks/api-key-exposures/api-key-exposure-created) event."
        },
        "api_key_rotation.created": {
          "description": "An [`api_key_rotation.created`](https://developer.paddle.com/webhooks/api-key-rotations/api-key-rotation-created) event."
        },
        "api_key_rotation.updated": {
          "description": "An [`api_key_rotation.updated`](https://developer.paddle.com/webhooks/api-key-rotations/api-key-rotation-updated) event."
        },
        "business.created": {
          "description": "A [`business.created`](https://developer.paddle.com/webhooks/businesses/business-created) event."
        },
        "business.imported": {
          "description": "A [`business.imported`](https://developer.paddle.com/webhooks/businesses/business-imported) event."
        },
        "business.updated": {
          "description": "A [`business.updated`](https://developer.paddle.com/webhooks/businesses/business-updated) event."
        },
        "client_token.created": {
          "description": "A [`client_token.created`](https://developer.paddle.com/webhooks/client-tokens/client-token-created) event."
        },
        "client_token.revoked": {
          "description": "A [`client_token.revoked`](https://developer.paddle.com/webhooks/client-tokens/client-token-revoked) event."
        },
        "client_token.updated": {
          "description": "A [`client_token.updated`](https://developer.paddle.com/webhooks/client-tokens/client-token-updated) event."
        },
        "customer.created": {
          "description": "A [`customer.created`](https://developer.paddle.com/webhooks/customers/customer-created) event."
        },
        "customer.imported": {
          "description": "A [`customer.imported`](https://developer.paddle.com/webhooks/customers/customer-imported) event."
        },
        "customer.updated": {
          "description": "A [`customer.updated`](https://developer.paddle.com/webhooks/customers/customer-updated) event."
        },
        "discount.created": {
          "description": "A [`discount.created`](https://developer.paddle.com/webhooks/discounts/discount-created) event."
        },
        "discount.imported": {
          "description": "A [`discount.imported`](https://developer.paddle.com/webhooks/discounts/discount-imported) event."
        },
        "discount.updated": {
          "description": "A [`discount.updated`](https://developer.paddle.com/webhooks/discounts/discount-updated) event."
        },
        "discount_group.created": {
          "description": "A [`discount_group.created`](https://developer.paddle.com/webhooks/discount-groups/discount-group-created) event."
        },
        "discount_group.updated": {
          "description": "A [`discount_group.updated`](https://developer.paddle.com/webhooks/discount-groups/discount-group-updated) event."
        },
        "meter.created": {
          "description": "A [`meter.created`](https://developer.paddle.com/webhooks/meters/meter-created) event.",
          "x-early-access": true
        },
        "meter.updated": {
          "description": "A [`meter.updated`](https://developer.paddle.com/webhooks/meters/meter-updated) event.",
          "x-early-access": true
        },
        "payment_method.saved": {
          "description": "A [`payment_method.saved`](https://developer.paddle.com/webhooks/payment-methods/payment-method-saved) event."
        },
        "payment_method.deleted": {
          "description": "A [`payment_method.deleted`](https://developer.paddle.com/webhooks/payment-methods/payment-method-deleted) event."
        },
        "payout.created": {
          "description": "A [`payout.created`](https://developer.paddle.com/webhooks/payouts/payout-created) event."
        },
        "payout.paid": {
          "description": "A [`payout.paid`](https://developer.paddle.com/webhooks/payouts/payout-paid) event."
        },
        "price.created": {
          "description": "A [`price.created`](https://developer.paddle.com/webhooks/prices/price-created) event."
        },
        "price.imported": {
          "description": "A [`price.imported`](https://developer.paddle.com/webhooks/prices/price-imported) event."
        },
        "price.updated": {
          "description": "A [`price.updated`](https://developer.paddle.com/webhooks/prices/price-updated) event."
        },
        "product.created": {
          "description": "A [`product.created`](https://developer.paddle.com/webhooks/products/product-created) event."
        },
        "product.imported": {
          "description": "A [`product.imported`](https://developer.paddle.com/webhooks/products/product-imported) event."
        },
        "product.updated": {
          "description": "A [`product.updated`](https://developer.paddle.com/webhooks/products/product-updated) event."
        },
        "report.created": {
          "description": "A [`report.created`](https://developer.paddle.com/webhooks/reports/report-created) event."
        },
        "report.updated": {
          "description": "A [`report.updated`](https://developer.paddle.com/webhooks/reports/report-updated) event."
        },
        "subscription.activated": {
          "description": "A [`subscription.activated`](https://developer.paddle.com/webhooks/subscriptions/subscription-activated) event."
        },
        "subscription.canceled": {
          "description": "A [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled) event."
        },
        "subscription.created": {
          "description": "A [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created) event."
        },
        "subscription.imported": {
          "description": "A [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported) event."
        },
        "subscription.past_due": {
          "description": "A [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due) event."
        },
        "subscription.paused": {
          "description": "A [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused) event."
        },
        "subscription.resumed": {
          "description": "A [`subscription.resumed`](https://developer.paddle.com/webhooks/subscriptions/subscription-resumed) event."
        },
        "subscription.trialing": {
          "description": "A [`subscription.trialing`](https://developer.paddle.com/webhooks/subscriptions/subscription-trialing) event."
        },
        "subscription.updated": {
          "description": "A [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated) event."
        },
        "transaction.billed": {
          "description": "A [`transaction.billed`](https://developer.paddle.com/webhooks/transactions/transaction-billed) event."
        },
        "transaction.canceled": {
          "description": "A [`transaction.canceled`](https://developer.paddle.com/webhooks/transactions/transaction-canceled) event."
        },
        "transaction.completed": {
          "description": "A [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed) event."
        },
        "transaction.created": {
          "description": "A [`transaction.created`](https://developer.paddle.com/webhooks/transactions/transaction-created) event."
        },
        "transaction.paid": {
          "description": "A [`transaction.paid`](https://developer.paddle.com/webhooks/transactions/transaction-paid) event."
        },
        "transaction.past_due": {
          "description": "A [`transaction.past_due`](https://developer.paddle.com/webhooks/transactions/transaction-past-due) event."
        },
        "transaction.payment_failed": {
          "description": "A [`transaction.payment_failed`](https://developer.paddle.com/webhooks/transactions/transaction-payment-failed) event."
        },
        "transaction.ready": {
          "description": "A [`transaction.ready`](https://developer.paddle.com/webhooks/transactions/transaction-ready) event."
        },
        "transaction.revised": {
          "description": "A [`transaction.revised`](https://developer.paddle.com/webhooks/transactions/transaction-revised) event."
        },
        "transaction.updated": {
          "description": "A [`transaction.updated`](https://developer.paddle.com/webhooks/transactions/transaction-updated) event."
        },
        "usage_balance.depleted": {
          "description": "A [`usage_balance.depleted`](https://developer.paddle.com/webhooks/usage-balances/usage-balance-depleted) event.",
          "x-early-access": true
        }
      }
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 datetime string of when this event occurred.",
      "title": "Timestamp",
      "examples": [
        "2024-10-12T07:20:50.52Z"
      ]
    },
    "notification_id": {
      "type": "string",
      "pattern": "^ntf_[a-z\\d]{26}$",
      "description": "Unique Paddle ID for this notification, prefixed with `ntf_`.",
      "title": "Notification ID",
      "examples": [
        "ntf_01ghbkd0frb9k95cnhwd1bxpvk"
      ]
    },
    "data": {
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^apkrot_[a-z\\d]{26}$",
          "description": "Unique Paddle ID for this API key rotation entity, prefixed with `apkrot_`.",
          "title": "Rotation ID",
          "examples": [
            "apkrot_01gm106t81w94gyjgsaqypkjkl"
          ]
        },
        "api_key_id": {
          "type": "string",
          "pattern": "^apikey_[a-z\\d]{26}$",
          "description": "Unique Paddle ID for this API key entity, prefixed with `apikey_`.",
          "title": "API Key ID",
          "examples": [
            "apikey_01gm106t81w94gyjgsaqypkjkl"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "completed",
            "canceled"
          ],
          "description": "Status of this API key rotation.",
          "title": "Rotation Status",
          "x-enum-descriptions": {
            "pending": {
              "description": "Rotation was created and the new secret was issued, but it hasn't been used yet. The current secret still works."
            },
            "completed": {
              "description": "The new secret was used and is now active. The old secret works until `expires_at`."
            },
            "canceled": {
              "description": "Rotation was canceled or replaced by a newer rotation before the new secret was used."
            }
          }
        },
        "grace_period_seconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 86400,
          "description": "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.",
          "title": "Grace Period"
        },
        "new_key_expires_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "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.",
              "title": "New Key Expires At",
              "examples": [
                "2024-10-12T07:20:50.52Z"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "expires_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "RFC 3339 datetime string.",
              "title": "Timestamp",
              "examples": [
                "2024-10-12T07:20:50.52Z"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "RFC 3339 datetime string of when the old secret stops working. `null` until the new secret is activated."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.",
          "title": "Created at",
          "examples": [
            "2024-10-12T07:20:50.52Z"
          ]
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.",
          "title": "Updated at",
          "examples": [
            "2024-10-13T07:20:50.52Z"
          ]
        }
      },
      "required": [
        "id",
        "api_key_id",
        "status",
        "grace_period_seconds",
        "new_key_expires_at",
        "expires_at",
        "created_at",
        "updated_at"
      ],
      "type": "object",
      "description": "New or changed entity."
    }
  }
}
```

## Example

```json
{
  "event_id": "evt_01jkdrb9yq2v6k4e1m3x8p7c5d",
  "event_type": "api_key_rotation.updated",
  "occurred_at": "2025-08-19T13:10:02.114209Z",
  "notification_id": "ntf_01jkdrba4hm0x2q8v6r9t3w1ye",
  "data": {
    "id": "apkrot_01jkas9tppn3bhadwpcyag45zd",
    "api_key_id": "apikey_01jkdpbhazdpn3wpcya45as9tg",
    "status": "completed",
    "grace_period_seconds": 3600,
    "new_key_expires_at": null,
    "expires_at": "2025-08-19T14:10:02.114209Z",
    "created_at": "2025-08-19T12:58:38.746382Z",
    "updated_at": "2025-08-19T13:10:02.114209Z"
  }
}
```