Permissions

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 that return customer portal URLs

  When a response can include authenticated URLs linking to the customer portal, your API key needs the customer_portal_session.write permission or they are not returned.

  Example: Without the customer_portal_session.write permission, listing subscriptions doesn't return the management_urls object containing authenticated links.

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

Available permissions

Related pages