Skip to main content
Polar is an open-source funding platform for developers. The theAuth plugin wires Polar checkout sessions and subscription webhooks to your user records, no Polar SDK required. The plugin exposes HTTP endpoints only. It does not add theauth.polar or theauth.plugins.polar to the instance, so to call the methods from your own code you create the module yourself (see Usage).

Setup

1

Get your credentials

From your Polar dashboard, go to Settings → API and create an access token. Under Webhooks, create an endpoint pointing to /api/theauth/auth/polar/webhook and copy the signing secret.
2

Configure the plugin

The checkout and subscription endpoints act on the authenticated user, resolved from auth.adapter or an auth.session token.

Usage

Create the module with the same config and your instance’s database:

Create a checkout session

Check subscription status

HTTP endpoints

The plugin registers three routes under your theAuth base path.

POST /auth/polar/checkout

Creates a checkout session. Requires an authenticated user.

GET /auth/polar/subscription

Returns the current subscription for the authenticated user.
Returns { "subscription": null } when no subscription is stored for the user.

POST /auth/polar/webhook

Receives webhook events from Polar. The webhook-signature header is verified with HMAC-SHA256 against webhookSecret, no session auth needed. A missing or invalid signature is rejected. Handled events:

Sandbox mode

Set sandbox: true to point at sandbox.api.polar.sh during development. Polar’s sandbox environment mirrors the production API and lets you test webhooks without real payments.

Reference

PolarConfig

PolarSubscription

theAuth stores Polar subscription data in polar_* columns of the users table (polar_customer_id, polar_subscription_id, polar_subscription_status, polar_product_id, polar_current_period_end, polar_cancel_at_period_end). You can query them directly with Drizzle or any SQL client.

Organizations

Scope subscription access to org members.

Admin

User management for subscription-gated features.

Hooks

Lifecycle hooks you can attach to your instance. For subscription changes use the onSubscriptionChange callback.

Additional fields

Store subscription metadata on user records.
Last modified on October 7, 2026