Skip to main content
Polar API supports multiple authentication methods depending on your use case. All API requests must be authenticated using one of the methods below.

​
API Base URL

All API requests should be made to: 
https://api.polar.sh

​
Authentication Methods

​
Personal Access Token (PAT)

Personal Access Tokens are ideal for server-side applications and scripts that need to access your personal resources.
1

Generate a token

Navigate to your Polar settings and create a new Personal Access Token.
2

Use the token

Include the token in the Authorization header of your API requests.
curl https://api.polar.sh/v1/customers \
  -H "Authorization: Bearer polar_pat_YOUR_TOKEN_HERE"
Personal Access Tokens have access to all resources in your personal account. Keep them secure and never commit them to version control.

​
Organization Access Token (OAT)

Organization Access Tokens are scoped to a specific organization and can have granular permissions.
1

Generate a token

Go to your organization settings and create a new Organization Access Token with the required scopes.
2

Configure scopes

Select only the scopes needed for your application:
  • products:read, products:write - Product management
  • customers:read, customers:write - Customer management
  • subscriptions:read, subscriptions:write - Subscription management
  • orders:read, orders:write - Order management
  • webhooks:read, webhooks:write - Webhook management
  • And many more…
3

Use the token

Include the token in the Authorization header.
curl https://api.polar.sh/v1/customers \
  -H "Authorization: Bearer polar_oat_YOUR_TOKEN_HERE"
Organization Access Tokens are recommended for production applications as they provide better security through scoped permissions.

​
OAuth 2.0

OAuth 2.0 is ideal for applications that need to access Polar resources on behalf of users.
1

Register your application

Create an OAuth 2.0 client in your Polar dashboard.
2

Request authorization

Redirect users to the authorization endpoint with your client ID and requested scopes.
3

Exchange code for token

After user approval, exchange the authorization code for an access token.
4

Make API requests

Use the access token to make authenticated requests on behalf of the user.
# Redirect user to:
https://api.polar.sh/v1/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=https://your-app.com/callback&
  scope=openid%20profile%20email%20products:read%20customers:read
For detailed OAuth 2.0 implementation guidance, see our OAuth 2.0 documentation.

​
Customer Session Tokens

Customer session tokens are specialized tokens for authenticating customers on your organization. These are created programmatically for customer-facing features. 
curl -X POST https://api.polar.sh/v1/customer-portal/sessions/create \
  -H "Authorization: Bearer YOUR_ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUSTOMER_ID"
  }'
Customer session tokens expire after 1 hour and are intended for short-lived customer portal sessions.

​
Available Scopes

When using OAuth 2.0 or Organization Access Tokens, you can request specific scopes:
  • openid - OpenID Connect authentication
  • profile - Read user profile
  • email - Read user email address
Each resource has read and write scopes:
  • organizations:read, organizations:write
  • products:read, products:write
  • customers:read, customers:write
  • subscriptions:read, subscriptions:write
  • orders:read, orders:write
  • benefits:read, benefits:write
  • discounts:read, discounts:write
  • webhooks:read, webhooks:write
  • events:read, events:write
  • meters:read, meters:write
  • files:read, files:write
  • license_keys:read, license_keys:write
  • checkouts:read, checkouts:write
  • checkout_links:read, checkout_links:write
  • custom_fields:read, custom_fields:write
  • refunds:read, refunds:write
  • payments:read
  • transactions:read, transactions:write
  • payouts:read, payouts:write
  • disputes:read
  • metrics:read
  • customer_portal:read, customer_portal:write - Customer portal access
  • customer_sessions:write - Create customer sessions

​
Rate Limiting

API requests are rate limited based on your authentication method:
  • Web sessions: Higher limits for dashboard usage
  • OAuth 2.0 clients: Per-client rate limiting
  • Organization tokens: Based on organization’s rate limit tier
  • Personal tokens: Default rate limiting
Rate limit headers are included in all API responses:
  • X-RateLimit-Limit - Request limit per window
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Unix timestamp when the limit resets

​
Best Practices

Secure Storage

Store tokens securely using environment variables or a secrets management service. Never hardcode them in your application.

Principle of Least Privilege

Request only the scopes your application needs. Use Organization Access Tokens with minimal permissions.

Token Rotation

Regularly rotate your tokens and implement token refresh for OAuth 2.0 applications.

Error Handling

Handle authentication errors gracefully and implement retry logic with exponential backoff.

​
Next Steps

Sandbox Environment

Test your integration in the sandbox environment

Customer State API

Learn how to check customer entitlements

Webhooks

Set up webhooks for real-time notifications

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us