For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL. 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.

Skip to content
Paddle Docs home

List API keys

Returns a paginated list of API keys.

GET/api-keys

Returns a paginated list of API keys. Use the query parameters to page through results.

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

Requires api_key.read permission.

Query parameters

afterstring
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_pageinteger
Default: 50

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
order_bystring
Default: id[ASC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: id.

Values
  • id[ASC]
    Order by id, ascending.
  • id[DESC]
    Order by id, descending.

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
idstringrequired
Example: apikey_01gm106t81w94gyjgsaqypkjkl
Unique Paddle ID for this API key entity, prefixed with apikey_.
Pattern: ^apikey_[a-z\d]{26}$
namestringrequired
Short name of this API key. Typically unique and human-identifiable.
Length: 1–150
descriptionstring | nullrequired
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
statusstringrequired
Default: active
Status of this API key.
Values
  • active
  • expired
  • revoked
permissionsarray | nullrequired
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.
Values
  • 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.
+ Show all values
  • 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.readearly access
    View meters.
  • meter.writeearly 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.readearly access
    View customers' usage balances.
  • usage_balance_unit.readearly access
    View usage balance units.
  • usage_balance_unit.writeearly access
    Create new usage balance units and modify existing usage balance unit information.
  • usage_event.writeearly access
    Record usage events to draw down customers' usage balances.
  • verification.read
    View verification progress, including step statuses.
exposed_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this API key was first exposed. null if never exposed.
expires_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this API key expires. null if never expires.
rotatablebooleanrequired
Whether this API key can be rotated.
last_used_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this API key was last used (accurate to within 1 hour). null if never used.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
keystringrequired
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_:]*\*\*\*\*$
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (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_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

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
{
  "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
    }
  }
}

Was this page helpful?