Permissions

Permissions grant an API key access to specific entities or allow it to take specific actions in Paddle.

You can assign permissions to a key when creating or updating it.

If your key doesn't have the correct permissions, it returns a forbidden error (403).

Permission types

Each permission targets an entity, like products, customers, or transactions, and is one of two types:

• entity.read
  Read and list the entity, or use it with the include parameter. Applies to GET requests and preview requests (POST or PATCH).
• entity.write
  Create, update, archive, and delete the entity. Applies to POST, PATCH, and DELETE requests. Write permission automatically includes read.

When permissions are required

Your API key needs permissions when working with:

• Operations that access entities
  Your key needs permission for any entity an operation returns or acts on. For example, listing adjustments requires the adjustment.read permission.
• Responses that use the include parameter
  Your key needs read permission for any entity added via the include parameter. For example, listing prices with include=product requires both price.read and product.read permissions.
• Entities that return customer portal URLs
  Authenticated customer portal URLs are only returned if the key has customer_portal_session.write. For example, without the customer_portal_session.write permission, listing subscriptions doesn't return the management_urls object containing authenticated links.
• Entities populated in simulated webhooks
  When simulating webhooks using real data, your API key needs permission to read the entity and any related entities included in webhook payloads but not nested in the parent. For example, creating a notification simulation with config.entities.subscription_id requires the subscription.read permission or the request fails.

When permissions aren't required

Your API key doesn't need permissions when working with:

• Nested entities in responses
  Entities nested within a response are included regardless of permissions. For 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 write permission for those entities. For example, creating an adjustment that updates a transaction only requires adjustment.write, not transaction.write.
• Parent entities
  You don't need permissions for a parent entity to access its child. For example, retrieving an address for a customer uses both address and customer path parameters, but only requires address.read, not customer.read.

Available permissions

Best practices

• Follow the principle of least privilege.
  Only assign the permissions a key actually needs. A key used to sync product catalog data doesn't need transaction.write.
• Create separate keys per integration or team.
  Issue a distinct key per system or team so you can revoke access without affecting others.
• Review and rotate keys when access requirements change.
  When access requirements change, update the key rather than leaving unused permissions in place.