Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/polarsource/polar/llms.txt

Use this file to discover all available pages before exploring further.

Customer sessions enable passwordless authentication for your customers to access their purchases, subscriptions, and account settings.

​
Request Session Code

Send a magic link code to a customer’s email address. 
POST /v1/customer-portal/customer-session/request

​
Request Body

​
email
string
required
The customer’s email address.
​
organization_id
string
required
Your organization ID (UUID format).
​
customer_id
string
Optional customer ID for disambiguation when multiple customers share the same email.

​
Response

​
status
number
202 - Request accepted. Email sent to customer.

​
Example

curl -X POST https://api.polar.sh/v1/customer-portal/customer-session/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "organization_id": "01234567-89ab-cdef-0123-456789abcdef"
  }'
For security, this endpoint always returns 202, even if the customer doesn’t exist. This prevents email enumeration attacks.

​
Multiple Customers

If multiple customers exist with the same email, the endpoint returns 409 with selection options: 
{
  "error": "customer_selection_required",
  "detail": "Multiple customers found for this email. Please select one.",
  "customers": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Acme Corp"
    },
    {
      "id": "fedcba98-7654-3210-fedc-ba9876543210",
      "name": "Personal"
    }
  ]
}
Retry the request with the selected customer_id.

​
Authenticate with Code

Exchange a verification code for a session token. 
POST /v1/customer-portal/customer-session/authenticate

​
Request Body

​
code
string
required
The 6-digit verification code from the email.

​
Response

​
token
string
The session token to use in Authorization headers. Format: polar_cst_...

​
Example

curl -X POST https://api.polar.sh/v1/customer-portal/customer-session/authenticate \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC123"}'
Response: 
{
  "token": "polar_cst_1a2b3c4d5e6f7g8h9i0j"
}

​
Error Response

If the code is invalid or expired (codes expire after 15 minutes): 
{
  "error": "invalid_or_expired_code",
  "detail": "This customer session code is invalid or has expired."
}

​
Introspect Session

Get information about the current session. 
GET /v1/customer-portal/customer-session/introspect

​
Headers

​
Authorization
string
required
Bearer token from authentication.

​
Response

​
expires_at
string
ISO 8601 timestamp when the session expires.
​
return_url
string
Optional URL to redirect to after session expires.

​
Example

curl https://api.polar.sh/v1/customer-portal/customer-session/introspect \
  -H "Authorization: Bearer polar_cst_1a2b3c4d5e6f7g8h9i0j"
Response: 
{
  "expires_at": "2024-12-31T23:59:59Z",
  "return_url": "https://example.com/portal"
}

​
Get Authenticated User

Retrieve details about the currently authenticated customer or member. 
GET /v1/customer-portal/customer-session/user

​
Headers

​
Authorization
string
required
Bearer token from authentication.

​
Response

​
type
string
Either "customer" or "member".
​
name
string
The user’s name.
​
email
string
The user’s email address.
​
customer_id
string
The associated customer ID (UUID).
​
member_id
string
The member ID if type is “member” (UUID).
​
role
string
The member’s role if type is “member”: owner, billing_manager, or member.

​
Example

curl https://api.polar.sh/v1/customer-portal/customer-session/user \
  -H "Authorization: Bearer polar_cst_1a2b3c4d5e6f7g8h9i0j"
Customer Response: 
{
  "type": "customer",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "customer_id": "01234567-89ab-cdef-0123-456789abcdef",
  "member_id": null,
  "role": null
}
Member Response: 
{
  "type": "member",
  "name": "John Doe",
  "email": "john@acme.com",
  "customer_id": "01234567-89ab-cdef-0123-456789abcdef",
  "member_id": "fedcba98-7654-3210-fedc-ba9876543210",
  "role": "billing_manager"
}

​
Session Lifecycle

1

Code Generation

When a customer requests access, a 6-digit code is generated and emailed to them. The code is valid for 15 minutes.
2

Authentication

The customer enters the code to exchange it for a session token. Once used, the code is invalidated.
3

Active Session

The session token grants access to the Customer Portal API. Sessions are long-lived but can be revoked.
4

Session Expiration

When the session expires, customers must request a new code to regain access.

​
Security Best Practices

Store session tokens securely. They grant full access to a customer’s account.
  • Never include session tokens in URLs or query parameters
  • Store tokens in httpOnly cookies or secure browser storage
  • Implement automatic logout after inactivity
  • Clear tokens when customers log out
  • Use HTTPS for all API requests

​
Development Mode

In development environments, verification codes are logged to the console for easy testing: 
╔══════════════════════════════════════════════════════════╗
║                                                          ║
║           🔑 CUSTOMER SESSION CODE: ABC123              ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝
This makes it easy to test authentication flows without checking email.

Build docs developers (and LLMs) love

Get started for freeTalk to us