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

Get an API key

Returns an API key using its ID.

GET/api-keys/{api_key_id}

Returns an API key using its ID.

The API key is returned with an obfuscated key. An API key can always get itself, even without the api_key.read permission.

Requires api_key.read permission.

Path parameters

api_key_idstringrequired
Example: apikey_01gm106t81w94gyjgsaqypkjkl
Unique Paddle ID for this API key entity, prefixed with apikey_.
Pattern: ^apikey_[a-z\d]{26}$

Response (200)

dataobjectrequired
Represents an API key entity.
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.
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"
  },
  "meta": {
    "request_id": "8f2c41c6-5e0b-4c8e-9a7d-3b1e6f0d2a94"
  }
}

Was this page helpful?