Permissions

Limit an API key's access to specific entities and actions in Paddle.

Permissions control what API keys can do. They help you keep data secure by limiting each key to only the access it needs. You can create different keys with tailored permissions for different users, teams, or systems. This acts as a guardrail, preventing unauthorized access to your entire account.

When creating or updating an API key, you can assign it specific permissions.

Permissions are scoped to specific entities in Paddle, such as products, customers, or transactions. You can select two types of permission to determine what the key can do with an entity:

  • Read - Entity (Read) or {entity}.read

    Read, list, and use the include parameter to include the entity in a response. Works for GET requests and preview requests (using POST or PATCH).

  • Write - Entity (Write) or {entity}.write

    Create, update, archive, and delete the entity. Works for POST, PATCH, and DELETE requests. Having write permission for an entity automatically includes read permission for that entity.

Select the correct permissions

The permissions a key needs depend on the operation being performed and what entities it's accessing.

Permissions required

You do need permissions when working with:

  • Operations that access entities

    For operations that return or take action on an entity, your API key needs permission for that entity.

    Example: Listing adjustments requires the adjustment.read permission.

  • Responses enriched with entities

    When using the include parameter to enrich a response, your API key needs permission for any included entities.

    Example: Listing prices with include=product requires both price.read and product.read permissions.

  • Entities to populate in simulated webhooks

    When providing an entity ID in config.entities, your API key needs permission to read that entity and any related entities included in webhook payloads but not nested in the parent. For the entity you're attempting to populate, the request fails without the read permission. For related entities, static examples are used if the key has no read permissions.

    Example: Creating a notification simulation with config.entities.subscription_id requires the subscription.read permission or the request fails. Without the transaction.read permission, related transactions will fall back to static examples in simulated payloads. Transactions aren't nested in subscriptions by default.

Permissions not required

You don't need permissions when working with:

  • Nested entities in responses

    When an operation returns different entities within the primary entity's response, these nested entities are included even without specific permissions for them.

    Example: A transaction response contains prices in the items array. These are included even if you only have transaction.read permission and not price.read.

  • Indirectly created or updated entities

    Operations that indirectly create or update entities don't require additional write permissions for those generated entities.

    Example: Creating an adjustment that updates a transaction only requires adjustment.write, not transaction.write.

  • Parent entities

    If an entity has a parent entity, it isn't a prerequisite that the permissions for the parent entities are needed.

    Example: Retrieving an address for a customer uses both address and customer path parameters, but only requires address.read, not customer.read.

Requests made with API keys that don't have the required permissions return a forbidden error (403).

Available permissions

EntityPermissionOperations
Products product.read
product.write
Prices price.read
price.write
Discounts discount.read
discount.write
Customers customer.read
customer.write
Addresses address.read
address.write
Businesses business.read
business.write
Payment methods payment_method.read
payment_method.write
Customer authentication tokenscustomer_auth_token.write
Customer portal sessionscustomer_portal_session.write
Transactions transaction.read
transaction.write
Subscriptions subscription.read
subscription.write
Adjustments adjustment.read
adjustment.write
Pricing previewtransaction.read
Reports report.read
report.write
Eventsnotification.read
Notification settings notification_setting.read
notification_setting.write
Notifications notification.read
notification.write
Notification logsnotification.read
Simulations notification_simulation.read
notification_simulation.write
Simulation runs notification_simulation.read
notification_simulation.write
Simulation run events notification_simulation.read
notification_simulation.write

Related pages