Authentication

Use Bearer authentication when making requests to the Paddle API. Get a key from Paddle > Developer tools > Authentication.

All requests to the Paddle API require authentication unless explicitly stated. The API uses Bearer authentication.

To authenticate, pass your Paddle API key using the Bearer header. For example:

1
1Authorization: Bearer bb4e69088ea07a98a90565ac610c63654423f8f1e2d48b39b5

Ways to authenticate

There are two ways to authenticate with the Paddle platform:

API keys

Used to interact with the Paddle API in your backend. For example, building subscription upgrade and downgrade workflows.

Intended for use server-side.
Must be kept secret.
Has full access to the data in your system.

Client-side tokens

Used to work with Paddle.js in your frontend. For example, launching a checkout and previewing prices or transactions.

Intended for use in your frontend.
Safe to publish in your app code.
Limited to opening checkouts, previewing prices, and previewing transactions.

To avoid exposing your API key, do not use an API key in your app code. Build functionality into your backend to handle requests to the Paddle API using an API key and serve just the information you need to your frontend. Endpoints in the API have an Access-Control-Allow-Origin header to block direct access from browsers.

Get an API key

To create and manage API keys, go to Paddle > Developer tools > Authentication. Click Generate API key under the "API keys" section.

Treat your API key like a password. Keep it safe and never share it with apps or people you don't trust.

It's good practice to store your API key as a secret in a credential management system. Refresh your API keys periodically and revoke keys that you're no longer using.

Get a client-side token

To create and manage client-side tokens, go to Paddle > Developer tools > Authentication. Click Generate client-side token under the "Client-side tokens" section.

Use your client-side token when initializing Paddle.js.

Test authentication

The quickest way to test your authentication is to send a request to the /event-types endpoint. This returns a list of the types of events that are included in the event stream. It returns data even if you haven't created any entities in Paddle yet.

GEThttps://api.paddle.com/event-types

cURL request

1
1curl https://api.paddle.com/event-types -H "Authorization: Bearer bb4e69088ea07a98a90565ac610c63654423f8f1e2d48b39b5"

Response

If successful, you should get a response that includes a data array and a meta object.

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": [
3    {
4      "name": "transaction.billed",
5      "description": "Occurs when a transaction is billed. Its status field changes to billed and billed_at is populated.",
6      "group": "Transaction",
7      "available_versions": [
8        1
9      ]
10    },
11    {
12      "name": "transaction.canceled",
13      "description": "Occurs when a transaction is canceled. Its status field changes to canceled.",
14      "group": "Transaction",
15      "available_versions": [
16        1
17      ]
18    },
19    {
20      "name": "transaction.completed",

If unsuccessful, Paddle returns a 403 error with information about what went wrong and how to troubleshoot.

Versioning

Errors

Sign up to get notified when our API evolves