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
The customer’s email address.
Your organization ID (UUID format).
Optional customer ID for disambiguation when multiple customers share the same email.
Response
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": "[email protected]",
"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"
}
]
}
customer_id.
Authenticate with Code
Exchange a verification code for a session token.
POST /v1/customer-portal/customer-session/authenticate
Request Body
The 6-digit verification code from the email.
Response
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"}'
{
"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
Bearer token from authentication.
Response
ISO 8601 timestamp when the session expires.
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"
{
"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
Bearer token from authentication.
Response
Either "customer" or "member".
The user’s email address.
The associated customer ID (UUID).
The member ID if type is “member” (UUID).
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"
{
"type": "customer",
"name": "Jane Smith",
"email": "[email protected]",
"customer_id": "01234567-89ab-cdef-0123-456789abcdef",
"member_id": null,
"role": null
}
{
"type": "member",
"name": "John Doe",
"email": "[email protected]",
"customer_id": "01234567-89ab-cdef-0123-456789abcdef",
"member_id": "fedcba98-7654-3210-fedc-ba9876543210",
"role": "billing_manager"
}
Session Lifecycle
Code Generation
When a customer requests access, a 6-digit code is generated and emailed to them. The code is valid for 15 minutes.
Authentication
The customer enters the code to exchange it for a session token. Once used, the code is invalidated.
Active Session
The session token grants access to the Customer Portal API. Sessions are long-lived but can be revoked.
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 ║
║ ║
╚══════════════════════════════════════════════════════════╝