Polar setup

Keylight integrates with Polar through Standard Webhooks: every paid order, subscription state change, and successful refund hits Keylight, and Keylight mints, renews, or refunds the matching license. There’s no OAuth — selling only needs the signed webhook and a shared HMAC secret.

Two optional flows do call the Polar API and need an organization token with the checkouts:write scope (step 4): upgrades and Test a purchase.

Tip

Despite the spec, Polar uses HMAC-SHA256, not Ed25519. The Standard Webhooks signing format is webhook-id . webhook-timestamp . body with base64 HMAC-SHA256 output. Keylight handles the parsing — you just need to paste the secret.

1. Enable Polar in the dashboard

From your dashboard, go to Settings → Integrations → Polar and click Enable Polar. Keylight reveals the webhook URL:

https://api.keylight.dev/webhooks/polar/<your-tenant-id>/live
https://api.keylight.dev/webhooks/polar/<your-tenant-id>/sandbox

Copy it — you’ll paste it into Polar’s webhook settings in step 3.

Caution

Polar Sandbox and Polar production are separate environments, and so are their Keylight slots. A sandbox endpoint must post to the /sandbox URL and carry the secret + product map you saved under Sandbox in Keylight. Sending sandbox deliveries to the /live URL verifies them against the live secret, which fails with 400 Invalid request.

The bare …/webhooks/polar/<your-tenant-id> URL (no environment segment) is the pre-sandbox form and still resolves to live.

2. Map the Polar product to a key type

Mapping lives on the app, not on the integration — one Polar product per key type:

Dashboard → your app → Key types → Pricing → pick the Sandbox or Live tab → the Polar row → Set

Paste the Product ID. In Polar, open the product and use the ⋯ → Copy Product ID menu — it looks like prod_….

Tip

There is no Price ID to find. Polar doesn’t issue price-level identifiers, and Keylight doesn’t want one: it reads data.product_id off each order event to pick the row. If you’re hunting for a Price ID in Polar’s dashboard, you’re looking for something that doesn’t exist.

The environment tab matters. A product mapped on Live does nothing for a sandbox purchase, and vice versa — sandbox and live keep independent maps, and a Polar sandbox organisation issues entirely different product IDs from your production one.

Unmapped products are rejected with 409 price_unmapped instead of being minted against an unknown app. Polar retries a 409, so adding the missing row fixes the order retroactively.

3. Configure the webhook in Polar

In the Polar dashboard:

1. Go to Settings → Webhooks → Add Endpoint.

2. Paste the Keylight URL from step 1 into URL.

3. Set Format to Raw.

4. Subscribe to these events:

   • order.created
   • refund.created
   • subscription.created
   • subscription.updated
   • subscription.active
   • subscription.canceled
   • subscription.revoked

   If you only sell one-time licenses, the two order/refund events are enough.

5. Set the Secret. Polar lets you type your own or generate a random one — either is fine. Copy it exactly as it appears.

Back in Keylight (Settings → Integrations → Polar), paste the secret into Webhook signing secret and save.

Caution

Paste the secret verbatim — no prefix to add, nothing to strip, no base64 encoding. Unlike Stripe, Polar’s secret is a plain string of your choosing, and Keylight keys the HMAC on those exact characters. A single trailing space breaks every delivery.

Tip

Leave order.refunded unchecked. Polar fires it alongside refund.created for the same refund. Keylight acts only on refund.created, which carries the exact refunded amount — subscribing to both is harmless but adds deliveries that resolve to nothing.

4. Add an API key (optional)

Only needed for upgrades and Test a purchase. Selling works on the signing secret alone — skip this otherwise.

In Polar, create an organization token with one scope:

Group	Scope
Checkouts	checkouts:write

Paste it into Polar API key on the matching slot in Settings → Integrations → Polar. Tokens aren’t interchangeable: one from sandbox.polar.sh works only in Sandbox, one from polar.sh only in Live.

Caution

Leave license_keys:* unticked. Those govern Polar’s own license-key feature, not Keylight’s — granting them widens the token for nothing.

An Expiration breaks upgrades and Test a purchase on that date while ordinary sales keep working. That partial failure is hard to place months later.

5. Test the connection

Polar has no “send test event” button, so the way to prove the wiring is a real sandbox purchase — which is also the only thing that exercises the whole path.

1. In your sandbox Polar organisation (sandbox.polar.sh — a separate account and separate product IDs from production), create a checkout link for the product you mapped. Leave its Metadata empty.
2. Open the link and pay with Stripe’s test card: 4242 4242 4242 4242, any future expiry, any CVC.
3. Read the result in Polar under Settings → Webhooks → your endpoint → Deliveries, and in Keylight under Dashboard → Licenses.

What the delivery response means:

• A 200 OK from Keylight with a fresh license record in Dashboard → Licenses means signature + product map are correct.
• 400 Invalid request → the signature didn’t verify. Almost always the secret doesn’t match character-for-character; less often, a proxy in front of Keylight stripped the webhook-id / webhook-timestamp headers.
• 409 price_unmapped → the event’s Product ID isn’t in your map (step 2).
• 204 No Content → Keylight verified the delivery but had nothing to do with it: an event type it doesn’t act on, or an order.created whose status isn’t yet paid.

What happens on a real sale

When a customer checks out, Polar fires order.created with data.status === 'paid'. Keylight verifies the Standard Webhooks signature, looks up the app+key-type from data.product_id, mints a license, and records the payment. Subscription renewals arrive as subscription.updated with data.status === 'active' and re-extend the license. subscription.canceled and subscription.revoked flip it to cancelled. A successful refund.created (where data.status === 'succeeded') flips the license to refunded.

Upgrades

Upgrades are brokered through Polar’s Checkout API, so they need the API key from step 4 — checkouts:write, on the Live slot.

With that in place, Keylight creates the upgrade checkout itself, stamping the customer’s current license key into the checkout metadata. Polar copies that onto the resulting order, and Keylight links the order to the existing license instead of issuing a second one. The key type’s Upgrade checkout URL is not used for Polar — leave it blank.

Caution

A checkout link can’t stand in for this, even though it has a Metadata field.

Polar’s Create Checkout Link form does let you attach metadata, and that metadata does reach the order. But it is fixed to the link — every customer who opens it carries the same values. An upgrade has to carry that one customer’s license key, so a shared link cannot express it.

Nor can you inject it per-customer through the URL. Checkout links accept a fixed set of query parameters — product_id, customer_email, customer_name, discount_code, amount, locale, theme, custom_field_data.{slug}, reference_id, utm_* — and silently drop anything else, including metadata[...]. A hand-built link carrying an upgrade key in the query string checks out and pays perfectly, then arrives with no upgrade key, and the customer gets a brand-new license instead of an upgrade.

Per-customer metadata means a checkout session created per customer, which is what the Checkout API does and why upgrades need the API key. Without one, Keylight returns polar_api_key_missing rather than falling back to a link that would mis-issue.

Upgrades on subscription key types aren’t supported yet (polar_subscription_upgrade_not_supported) — changing a plan means amending the existing Polar subscription, not paying for a new one-time checkout.

Disconnecting

Settings → Integrations → Polar → Disconnect clears the signing secret and the product map. Existing licenses are untouched — only new webhook deliveries stop minting.