List, check, and rotate API keys using the Paddle API

What's new?

You can now list and get the API keys on your account using the Paddle API, and rotate a rotatable key from your own tooling. We've also added webhooks that let you know when a key is rotated.

AI agents connected to the Paddle MCP server can list and get API keys too, so you can ask an agent which keys are on your account and when they expire.

How it works

API keys authenticate requests to the Paddle API. Rotatable keys can have their secret replaced while keeping their ID, name, and permissions, so there's nothing to reconfigure in Paddle.

Until now, you could only rotate API keys automatically with AWS Secrets Manager. Otherwise, you had to replace them by hand: create a new key in the Paddle dashboard, swap it in everywhere it's used, then revoke the old one.

Now, you can:

• List and get API keys
  API keys are returned with their name, status, permissions, expiry date, and when they were last used. The key itself is obfuscated. Use these operations to audit the keys on your account, check which permissions a key has, or find keys that are about to expire.
• Rotate an API key
  Rotatable keys can rotate themselves, so you can build rotation into any secrets manager, scheduler, or platform. Create a rotation to get a new secret for a key, start using it, and let the old secret stop working after a grace period that you choose.
• Check a rotation
  List or get the rotations for a key to see whether the new secret is active and when the old secret stops working.
• Get notified about rotations
  Subscribe to api_key_rotation.created and api_key_rotation.updated to find out when a key is rotated and when the new secret is activated. Use them to spot rotations you didn't start yourself.

Listing and getting API keys requires the new api_key.read permission. Rotation operations don't require a permission, because a key can only rotate itself. Only keys created as rotatable support rotation.

Example

This example rotates a sandbox API key with a one-hour grace period. Paddle returns the new secret in new_key. The rotation is pending until the new secret is used for the first time.

{
  "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"
  }
}

Next steps

This change is available in version 1 of the Paddle API. It's a non-breaking change, meaning it doesn't impact existing integrations.

To get started, assign the api_key.read permission to a key in the Paddle dashboard and list your API keys. To rotate keys from your own tooling, create a rotatable API key and follow Rotate using the Paddle API. If your keys aren't rotatable, replace them with rotatable keys first.