> 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.

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

Audit the API keys on your account and swap a key's secret from your own tooling, without logging in to the Paddle dashboard or using AWS Secrets Manager.

---

## 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](https://developer.paddle.com/sdks/ai/paddle-mcp.md) 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](https://developer.paddle.com/api-reference/api-keys.md) authenticate requests to the Paddle API. [Rotatable keys](https://developer.paddle.com/api-reference/about/authentication.md#rotatable) 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**](https://developer.paddle.com/api-reference/api-keys/list-api-keys.md)  
  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**](https://developer.paddle.com/api-reference/api-keys/create-api-key-rotation.md)  
  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**](https://developer.paddle.com/api-reference/api-keys/list-api-key-rotations.md)  
  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`](https://developer.paddle.com/webhooks/api-keys/api-key-rotation-created.md) and [`api_key_rotation.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-rotation-updated.md) 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.

{% callout type="info" %}
You can't create, update, or revoke API keys using the API. Manage them in **Paddle > My account > Settings > Authentication**.
{% /callout %}

## 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.

{% api-example method="POST" path="/api-keys/{api_key_id}/rotations" href="/api-reference/api-keys/create-api-key-rotation" %}

```json
{
  "grace_period_seconds": 3600,
  "new_key_expires_at": "2027-02-01T00:00:00Z"
}
```

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

{% /api-example %}

## 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](https://developer.paddle.com/api-reference/api-keys/list-api-keys.md). To rotate keys from your own tooling, [create a rotatable API key](https://developer.paddle.com/api-reference/about/authentication.md#rotatable) and follow [Rotate using the Paddle API](https://developer.paddle.com/api-reference/about/rotate-api-keys.md#rotate-with-api). If your keys aren't rotatable, [replace them with rotatable keys](https://developer.paddle.com/api-reference/about/rotate-api-keys.md#replace-key) first.

[To learn how Paddle's API keys are built, and why rotation swaps the secret without changing the key's ID, read our post on the Paddle.engineering blog.](https://paddle.engineering/blog/paddle-api-key-format-design)
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| GET /api-keys | API operation | added | API keys | List the API keys on your account, with an obfuscated key. |
| GET /api-keys/{api_key_id} | API operation | added | API keys | Get an API key using its ID, with an obfuscated key. |
| `api_key.read` | Permission | added | API keys | View API keys, including their names, status, and permissions. The full key is never returned. |
| `api_key_rotation` | Entity | added | API keys | Describes a change of an API key's secret. The key keeps its ID, name, and permissions. |
| POST /api-keys/{api_key_id}/rotations | API operation | added | API keys | Create a rotation for a rotatable API key. Returns the new secret in `new_key`. |
| GET /api-keys/{api_key_id}/rotations | API operation | added | API keys | List rotations for a rotatable API key. |
| GET /api-keys/{api_key_id}/rotations/{rotation_id} | API operation | added | API keys | Get a rotation for a rotatable API key. |
| `api_key_rotation.created` | Webhook | added | api_key_rotation.created | Occurs when an API key is rotated and a new secret is issued. |
| `api_key_rotation.updated` | Webhook | added | api_key_rotation.updated | Occurs when an API key rotation is completed or canceled. |
| `api_key_cannot_be_rotated` | Error | added | API keys | Returned when you try to rotate an API key that wasn't created as rotatable. |