Strengthen your integration security with enhanced API keys
API keys now have a new standardized format, improved security features, and better management options — including permissions and expiry dates.
What's new?
We've upgraded API keys with enhanced security features and management capabilities that make your integration more secure.
Previously, API keys were simple 50-character strings with no built-in information about their environment or purpose. Keys had unlimited lifespans and full access to all data on your account. With this release, API keys:
- Follow a standardized format that identifies their environment with
live_orsdbx_. - Are only visible when created.
- Can be assigned specific permissions to control access.
- Show when they were last used, helping you identify inactive keys and suspicious activity.
- Can be easily managed through a redesigned dashboard page.
How it works
API keys are now identified by a new format:
121pdl_live_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQO
2pdl_sdbx_apikey_01gtgztp8f4kek3yd4g1wrksa3_q6TGTJyvoIz7LDtXT65bX7_AQOWhen creating or editing an API key, select granular permissions to control which entities and operations the API key can access.
Setting an expiration date for the API key enforces regular rotation. This defaults to 90 days. The new api_key.expiring and api_key.expired events enable subscription to notifications for when API keys are expiring and expired, allowing you to build workflows to rotate keys and minimize disruption before they expire.
You can create multiple API keys with different permissions and expiry dates to give you more control over who has access to your data and for how long.
API keys can only be viewed once upon creation and must immediately be stored securely.
After using an API key, the last used date appears as Last Used in the list of API keys at Paddle > Developer Tools > Authentication.
Summary of changes
Notifications
This is a summary of the new webhook and email notification events:
api_key.created | Occurs when an API key is created. |
api_key.updated | Occurs when an API key is updated. |
api_key.expiring | Occurs when an API key expires in seven days. |
api_key.expired | Occurs when an API key has expired. |
api_key.revoked | Occurs when an API key is revoked. |
Permissions
This is a summary of the new permissions available to API keys:
| Entity | Permission | Description |
|---|---|---|
| Products | product.read | View products and include product data in API responses. |
product.write | Create new products and modify existing product information. | |
| Prices | price.read | View prices and include price data in API responses. |
price.write | Create new prices and modify existing price information. | |
| Discounts | discount.read | View discounts and include discount data in API responses. |
discount.write | Create new discounts and modify existing discount information. | |
| Customers | customer.read | View customers, including credit balances, and include customer data in API responses. |
customer.write | Create new customers and update existing customer information. | |
| Addresses | address.read | View customer addresses and include address data in API responses. |
address.write | Create and update customer addresses. | |
| Businesses | business.read | View customer businesses and include business data in API responses. |
business.write | Create and update customer businesses. | |
| Payment methods | payment_method.read | View saved payment methods for customers. |
payment_method.write | Delete payment methods for customers. | |
| Customer authentication tokens | customer_auth_token.write | Generate authentication tokens for customers. |
| Customer portal sessions | customer_portal_session.write | Create new customer portal sessions for customers to manage their subscriptions, payment methods, and more. |
| Transactions | transaction.read | View transactions, preview transactions, access invoices, and include transaction data in API responses. |
transaction.write | Create, update, and revise transactions, and update payment methods. | |
| Subscriptions | subscription.read | View subscription information and preview subscription updates and charges. |
subscription.write | Create one-time charges, update subscriptions, and manage subscription status. | |
| Adjustments | adjustment.read | View adjustments and credit notes for transactions. |
adjustment.write | Create new adjustments for transactions. | |
| Pricing preview | transaction.read | Preview prices based on different parameters. |
| Reports | report.read | View and download report data. |
report.write | Create new reports. | |
| Events | notification.read | View event history and include event data in API responses. |
| Notification settings | notification_setting.read | View settings for notifications. |
notification_setting.write | Create, update, and delete notification settings. | |
| Notifications | notification.read | View sent notifications. |
notification.write | Replay notifications. | |
| Notification logs | notification.read | View notification delivery logs. |
| Simulations | notification_simulation.read | View notification simulations. |
notification_simulation.write | Create and modify notification simulations. | |
| Simulation runs | notification_simulation.read | View runs for notification simulations. |
notification_simulation.write | Create a run for a notification simulation. | |
| Simulation run events | notification_simulation.read | View events within a run for a notification simulation. |
notification_simulation.write | Replay events within a run for a notification simulation. |
Next steps
This change is live in v1 of the Paddle API. Existing API keys created before May 6, 2025 are now considered legacy API keys.
Legacy API keys continue to work without disruption, with no set timeline for deprecation.
We still recommend you migrate to the new API keys as soon as possible. Check the permissions reference to understand which permissions are needed for the requests you make, and assign those permissions to the API key when creating it.