TL;DR
Production Base URL
https://api.polar.sh/v1
Sandbox Base URL
https://sandbox-api.polar.sh/v1
Auth (Organization)
Use an Organization Access Token (OAT) in the
Authorization: Bearer
headerAuth (Customer Portal)
Use a Customer Access Token created via
/v1/customer-sessions/
Base URLs
Environment | Base URL | Purpose |
---|---|---|
Production | https://api.polar.sh/v1 | Real customers & live payments |
Sandbox | https://sandbox-api.polar.sh/v1 | Safe testing & integration work |
The sandbox environment is fully isolated—data, users, tokens, and
organizations created there do not affect production. Create separate tokens
in each environment.
Authentication
Organization Access Tokens (OAT)
Use an OAT to act on behalf of your organization (manage products, prices, checkouts, orders, subscriptions, benefits, etc.).Create OATs in your organization settings. See: Organization Access
Tokens
Never expose an OAT in client-side code, public repos, or logs. If leaked, it
will be revoked automatically by our secret scanning integrations.
Customer Access Tokens
Do not use OATs in the browser. For customer-facing flows, generate a Customer Session server-side, then use the returned customer access token with the Customer Portal API to let a signed-in customer view their own orders, subscriptions, and benefits.Core API vs Customer Portal API
Aspect | Core API | Customer Portal API |
---|---|---|
Audience | Your server / backend | One of your customer |
Auth Type | Organization Access Token (OAT) | Customer Access Token |
Scope | Full org resources (products, orders, subscriptions, benefits, checkout) | Only the authenticated customer’s data |
Typical Use | Admin dashboards, internal tools, automation, provisioning | Building a custom customer portal or gated app |
Token Creation | Via dashboard (manual) | Via /v1/customer-sessions/ (server-side) |
Sensitive Operations | Yes (create/update products, issue refunds, etc.) | No (read/update only what the customer owns) |
The Customer Portal API is a restricted surface designed for safe exposure
in user-facing contexts (after exchanging a session). It cannot perform
privileged org-level mutations like creating products or issuing refunds.
Quick Examples
Using SDKs
All official SDKs accept aserver
parameter for sandbox usage:
Rate Limits
Polar API has rate limits to ensure fair usage and maintain performance. The limits are as follows:- 300 requests per minute per organization/customer or OAuth2 Client.
- 3 requests per second for unauthenticated license key validation, activation, and deactivation endpoints.
429 Too Many Requests
response. The response will include a Retry-After
header indicating how long you should wait before making another request.
Organizations requiring higher rate limits for production workloads may
contact our support team to discuss elevated limits.