Providers / Paddle
Payments
Paddle API keys and credentials
What every Paddle credential a founder holds does, whether it expires, and what tends to break. Each fact links to Paddle's own docs.
At a glance
| Credential | Expiry | Permissions |
|---|---|---|
| Paddle dashboard login | Not documented | – |
| API key (server-side) | You choose, default 90 days, max 1 year | Can be scoped |
| Client-side token (Paddle.js) | Not documented | Can be scoped |
| Notification destination secret key | Doesn't expire | Full access only |
Each credential
Paddle dashboard login
- Not documented
Dashboard login. Session and 2FA policy not documented on the pages reviewed. Keep team members and roles managed in the dashboard.
API key (server-side)
- You choose, default 90 days, max 1 year
- Can be scoped
Created in the Paddle dashboard (exact menu path not confirmed). An expiry date can be set at creation and is strongly recommended; the default is 90 days from creation and the maximum is one year from creation. Expired keys cannot be revalidated, so replace them by creating a new key. Permissions are set per key; requests without the needed permission return 403 forbidden. The Rotatable option must be enabled at creation and cannot be changed later. Rotatable keys have their expiry extended automatically when rotated (documented for AWS Secrets Manager integration). Keys created before 2025-05-06 are legacy keys with no permissions support; replace them. The page does not show how to view an existing key's expiry after creation.
Client-side token (Paddle.js)
- Not documented
- Can be scoped
Safe to publish in frontend code. Prefixed test_ (sandbox) or live_ (production) followed by 27 characters. Limited to opening checkouts, previewing prices and previewing transactions; API keys must not be used with Paddle.js. The docs describe revocation, but no expiry or lifetime field. Revocation is permanent and is done by PATCHing the token status to revoked; confirm the token is not in use in production first. No maximum number of tokens stated.
Notification destination secret key
- Doesn't expire
- Full access only
Paddle generates one secret key per notification destination. It does not expire or rotate automatically, per the docs. Retrieve it from the destination's Edit view or through GET /notification-settings/{id} (endpoint_secret_key). Rotation is not supported yet; to replace a suspected compromised key, delete the destination and create a new one. Webhook signatures (Paddle-Signature header) must be verified against the raw request body.
What usually goes wrong
- API key created with the default 90-day expiry expires and server-side calls start returning errors until a new key is deployed
- Legacy API key (created before 2025-05-06) without permissions remains in use after the team assumed it was scoped
- Notification destination secret is not updated after the destination is recreated, so every webhook fails signature verification
- Webhook handler verifies a parsed or re-serialized body instead of the raw request body
- Sandbox client-side token (test_ prefix) shipped to production checkout
- Rotatable option not enabled at key creation, forcing a manual replacement later
Renewals and billing
Transactions (GET /transactions) carry billed and created dates and totals; filter by created_at and billed_at. Address data only with include=address. Fee fields not yet confirmed.
What Paddle's docs don't say
We couldn't confirm these from official docs, so don't rely on them either way:
- Whether an existing API key's expiry can be read through the API or only in the dashboard
- Whether the Rotatable automatic expiry extension applies outside the AWS Secrets Manager integration
- Dashboard login session lifetime and 2FA policy
- Payout fees and timing
- Whether client-side tokens have any expiry or domain restriction (none found in docs)
- Whether usage or spend data is available through the API
- Exact dashboard label for transaction.read and how to set it in the UI
- Paddle rate limit (linked page not read)
- Whether reports (report.read) give a daily revenue view cheaper than transaction lists
- Whether transactions can be listed for a date range without customer address fields (the customer include was not fully read)
- Whether the API exposes key expiry (not found)
Rotating or replacing a Paddle key
The steps are the same for most providers: make the new key, deploy it everywhere the old one is used, check it works, then revoke the old one. Our guides walk through it:
Sources
- developer.paddle.com/api-reference/about/authentication
- developer.paddle.com/paddle-js/about/client-side-tokens
- developer.paddle.com/api-reference/client-tokens/overview
- developer.paddle.com/webhooks/about/signature-verification
- www.paddle.com/pricing
- developer.paddle.com/api-reference/transactions/list-transactions
- developer.paddle.com/api-reference/about/permissions
Related providers
Keep track of every Paddle key
StackHangar stores your Paddle keys in an encrypted vault, grouped by the product they belong to, warns you before they expire, and walks you through rotating them. We can't read your secrets.