> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> To search these docs, send a `GET` request to `https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question>` with a URL-encoded question. No authentication needed. It returns a JSON array of `{content, source_url}`, most relevant first.

# GET /api-keys

**List API keys**

Returns a paginated list of API keys. Use the query parameters to [page through results](https://developer.paddle.com/api-reference/about/pagination).

API keys are returned with an obfuscated `key`. The full key is only returned when it's created.

**Required permissions:** `api_key.read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | string | optional | Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations. |
| `per_page` | integer | optional | Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.

Default: `50`; Maximum: `200`. (Max: 200; default: `50`) |
| `order_by` | string | optional | Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.

Valid fields for ordering: `id`. (default: `"id[ASC]"`) |

Values for `order_by`:

- `id[ASC]` — Order by `id`, ascending.
- `id[DESC]` — Order by `id`, descending.

## Response (200)

- `data`: array (required)
  - `id`: string (required) — Unique Paddle ID for this API key entity, prefixed with `apikey_`. (pattern: `^apikey_[a-z\d]{26}$`)
  - `name`: string (required) — Short name of this API key. Typically unique and human-identifiable. (Length: 1–150)
  - `description`: string | null (required) — Short description of this API key. Typically gives details about what the API key is used for and where it's used. (Length: 1–250)
  - `status`: string (required) — Status of this API key. (default: `"active"`)
    - `active`
    - `expired`
    - `revoked`
  - `permissions`: array | null (required) — Permissions assigned to this API key. Determines what actions the API key can perform. `null` for legacy API keys, whose access doesn't come from permissions.
    - `account.read` — View the business identity of your account, including legal name, display name, website, and contact email.
    - `account.write` — Update the contact email for your account.
    - `address.read` — View customer addresses and include address data in API responses.
    - `address.write` — Create and update customer addresses.
    - `adjustment.read` — View adjustments and credit notes for transactions.
    - `adjustment.write` — Create new adjustments for transactions.
    - `api_key.read` — View API keys, including their names, status, and permissions. The full key is never returned.
    - `balance_currency.read` — View balance currency settings for your account.
    - `balance_currency.write` — Update balance currency settings for your account.
    - `business.read` — View customer businesses and include business data in API responses.
    - `business.write` — Create and update customer businesses.
    - `checkout_domain.read` — View checkout domains, their approval status, and payment method verification status.
    - `checkout_domain.write` — Delete checkout domains, and trigger payment method verification (Apple Pay) for approved checkout domains.
    - `checkout_settings.read` — View checkout settings for your account.
    - `checkout_settings.write` — Update checkout settings for your account.
    - `client_token.read` — View client-side tokens.
    - `client_token.write` — Create and update client-side tokens.
    - `currency_conversion.read` — View currency conversion settings for your account.
    - `currency_conversion.write` — Update currency conversion settings for your account.
    - `customer.read` — View customers, including credit balances, and include customer data in API responses.
    - `customer.write` — Create new customers and update existing customer information.
    - `customer_auth_token.write` — Generate authentication tokens for customers.
    - `customer_portal_session.write` — Create new customer portal sessions for customers to manage their subscriptions, payment methods, and more.
    - `discount.read` — View discounts and include discount data in API responses.
    - `discount.write` — Create new discounts and modify existing discount information.
    - `meter.read` (early access) — View meters.
    - `meter.write` (early access) — Create new meters and modify existing meter information.
    - `metrics.read` — View metrics data including revenue, subscribers, and conversion timeseries.
    - `notification.read` — View event history, sent notifications, notification delivery logs, and include event data in API responses.
    - `notification.write` — Replay notifications.
    - `notification_setting.read` — View settings for notifications.
    - `notification_setting.write` — Create, update, and delete notification settings.
    - `notification_simulation.read` — View notification simulations, simulation runs, and events within a simulation run.
    - `notification_simulation.write` — Create and modify notification simulations, create a run for a simulation, and replay events within a run for a simulation.
    - `payment_method.read` — View saved payment methods for customers.
    - `payment_method.write` — Delete payment methods for customers.
    - `price.read` — View prices and include price data in API responses.
    - `price.write` — Create new prices and modify existing price information.
    - `product.read` — View products and include product data in API responses.
    - `product.write` — Create new products and modify existing product information.
    - `report.read` — View and download report data.
    - `report.write` — Create new reports.
    - `statement_descriptor.read` — View statement descriptor settings for your account.
    - `statement_descriptor.write` — Update statement descriptor settings for your account.
    - `subscription.read` — View subscriptions and preview subscription updates and charges.
    - `subscription.write` — Create one-time charges, update subscriptions, and manage subscription status.
    - `subscription_history.read` — View subscription history entries for a subscription.
    - `tax_settings.read` — View tax settings for your account.
    - `tax_settings.write` — Update tax settings for your account.
    - `transaction.read` — View transactions, preview transactions and prices, access invoices, and include transaction data in API responses.
    - `transaction.write` — Create, update, and revise transactions, and update payment methods.
    - `usage_balance.read` (early access) — View customers' usage balances.
    - `usage_balance_unit.read` (early access) — View usage balance units.
    - `usage_balance_unit.write` (early access) — Create new usage balance units and modify existing usage balance unit information.
    - `usage_event.write` (early access) — Record usage events to draw down customers' usage balances.
    - `verification.read` — View verification progress, including step statuses.
  - `exposed_at`: string (date-time) | null (required) — RFC 3339 datetime string of when this API key was first exposed. `null` if never exposed.
  - `expires_at`: string (date-time) | null (required) — RFC 3339 datetime string of when this API key expires. `null` if never expires.
  - `rotatable`: boolean (required) — Whether this API key can be rotated.
  - `last_used_at`: string (date-time) | null (required) — RFC 3339 datetime string of when this API key was last used (accurate to within 1 hour). `null` if never used.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `key`: string (required) — An obfuscated version of this API key, prefixed with `pdl_` and containing `_apikey_`. Legacy API keys have no prefix, so only the first characters of the key are shown, followed by `****`. (pattern: `^[a-z\d_:]*\*\*\*\*$`)
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Keys used for working with paginated results.
    - `per_page`: integer (required) — Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (uri) (required) — URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`.
    - `has_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer — Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns `100001` to indicate that more than 100,000 entities match. Returns `-1` when counting is skipped or couldn't be calculated.

Use `has_more` and `next` to page through all results rather than relying on `estimated_total` for an exact count.

### Response example

```json
{
  "data": [
    {
      "id": "apikey_01jkdpbhazdpn3wpcya45as9tg",
      "name": "CRM integration",
      "description": "Used to authenticate with the API for storing Paddle customer data in our CRM.",
      "key": "pdl_live_apikey_01jkdpbhaz****",
      "status": "active",
      "permissions": [
        "address.read",
        "business.read",
        "customer.read",
        "subscription.read",
        "transaction.read"
      ],
      "exposed_at": null,
      "expires_at": "2026-03-26T06:58:38.517Z",
      "rotatable": true,
      "last_used_at": "2025-10-20T09:12:44.000Z",
      "created_at": "2025-03-26T06:58:38.517Z",
      "updated_at": "2025-03-26T06:58:38.517Z"
    },
    {
      "id": "apikey_01jkdpcy050kbc638ekh5ps5hj",
      "name": "Fulfillment service",
      "description": "Used by our backend to provision access when a subscription is created or changes.",
      "key": "pdl_live_apikey_01jkdpcy05****",
      "status": "active",
      "permissions": [
        "customer.read",
        "price.read",
        "product.read",
        "subscription.read"
      ],
      "exposed_at": null,
      "expires_at": null,
      "rotatable": false,
      "last_used_at": "2025-10-21T14:03:10.000Z",
      "created_at": "2025-02-12T10:41:02.811Z",
      "updated_at": "2025-02-12T10:41:02.811Z"
    }
  ],
  "meta": {
    "request_id": "4a9840c3-1e06-4873-9147-6d467938f992",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/api-keys?after=apikey_01jkdpcy050kbc638ekh5ps5hj",
      "has_more": false,
      "estimated_total": 2
    }
  }
}
```