Configuration

Set up sign-in and payments

Create the Google, GitHub, and Polar credentials your project needs, and put each half in the right place.

apps/web signs users in with Google and GitHub, and charges them through Polar. Each provider gives you two things: a public identifier that goes into Git, and a secret that goes into your secret store.

Every key below is required, so apps/web doesn't start until each one holds a value. If you aren't using a provider yet, put a stand-in such as unused in its keys and come back later. The product starts and deploys, and only that provider's feature fails when you first use it.

Where each value goes

KeyNeeded forGoes in
GOOGLE_CLIENT_IDGoogle sign-in (@app/layer-auth)apps/web/.env.<context>, in Git
GOOGLE_CLIENT_SECRETGoogle sign-in (@app/layer-auth)Your secret store
GITHUB_CLIENT_IDGitHub sign-in (@app/layer-auth)apps/web/.env.<context>, in Git
GITHUB_CLIENT_SECRETGitHub sign-in (@app/layer-auth)Your secret store
POLAR_ACCESS_TOKENPayments (@app/layer-payments)Your secret store
POLAR_WEBHOOK_SECRETPayments (@app/layer-payments)Your secret store

POLAR_SERVER picks the Polar environment. It's already set in every value file, so it needs nothing from you until you go live.

Set up your secret store covers which folder the secrets go in. Environment values explains why the client IDs are committed instead.

Register these callback URLs

Create a separate OAuth application for each context you deploy, and a separate Polar organization for each context. Each one has a different origin, and a callback URL is registered per exact URL.

For local development, the origin is http://web.<slug>.localhost in the main checkout, and http://<worktree label>.web.<slug>.localhost in a worktree. For a deployed context, it's the NUXT_PUBLIC_APP_BASE_URL you wrote into that context's apps/web/.env.<context> — Project identity explains the shape each one takes. A product mounted under the site puts its mount, the NUXT_APP_BASE_URL it deploys with, before /api, so example.com/app/ registers https://example.com/app/api/auth/callback/google. Attaching a domain covers the mount.

A pull request preview gets a different origin per pull request, so no callback URL can be registered for it in advance. Social sign-in fails on a preview, and that's expected.
ProviderCallback URL
Google<origin>/api/auth/callback/google
GitHub<origin>/api/auth/callback/github
Polar<origin>/api/webhooks/polar (webhook endpoint)

Google

Create an OAuth 2.0 client ID of type Web application in the Google Cloud console, under APIs & Services > Credentials. Add <origin>/api/auth/callback/google as an authorized redirect URI for each deployed context.

Google sign-in doesn't work locally. Google refuses every *.localhost redirect URI, so test it on development instead.

Google's OAuth 2.0 setup guide covers the consent screen and publishing.

The console gives you a client ID and a client secret. Put the ID in apps/web/.env.development and the secret in your secret store.

GitHub

Create an OAuth app under Settings > Developer settings > OAuth Apps, and set the authorization callback URL to http://web.<slug>.localhost/api/auth/callback/github. Tick Allow wildcard matching, so the one callback also covers every worktree's subdomain. See GitHub's guide to creating an OAuth app.

GitHub shows the client ID immediately and generates the client secret on request. The secret is shown once.

Polar

Use the Polar sandbox for everything except production. A token issued by one Polar environment doesn't work against the other, and the mismatch surfaces at the first API call rather than at startup — so check which dashboard you're in before copying a token.

Create one organization per context

Give each Runtime Context its own organization, local included. In a shared organization, sign-up refuses an email another context already used, and each context's webhook receives the other's purchases.

Runtime ContextDashboardName and slugWebhook
localsandbox<slug>-web-localYour Funnel URL — see Receive webhooks locally
developmentsandbox<slug>-web-development<origin>/api/webhooks/polar
previewsandbox<slug>-web-previewNone — put a stand-in in its POLAR_WEBHOOK_SECRET
stagingsandbox<slug>-web-staging<origin>/api/webhooks/polar
productionpolar.shPROJECT_DISPLAY_NAME, PROJECT_SLUG<origin>/api/webhooks/polar

<slug> is your PROJECT_SLUG. Create each organization when you add its context. Production's takes your display name because Polar's emails to your customers carry it.

To create an organization:

  1. Sign in to the dashboard the table names. The sandbox keeps its own accounts, so sign up there the first time.
  2. Select the current organization's name at the bottom of the sidebar, then select New Organization. A new account starts on this form.
  3. Enter the name and the slug from the table.

preview has no webhook because each pull request serves from its own origin. Every pull request shares preview's organization but starts with an empty database, so sign-up refuses an email an earlier pull request used. Sign up with a new address on each one, such as you+pr12@example.com.

Copy the organization's credentials

Take both credentials from the organization the table names for the context. They come from two different pages:

  1. POLAR_ACCESS_TOKEN — create an organization access token under Settings > Developer. See Polar authentication.
  2. POLAR_WEBHOOK_SECRET — add a webhook pointing at <origin>/api/webhooks/polar, then copy the signing secret from that webhook's own settings page. It isn't the access token, and the developer settings page doesn't show it. Set the webhook's API version to the one in the @polar-sh/sdk/<version> import of packages/layer-payments/server/api/webhooks/polar.post.ts. The handlers expect that version's payload shape.

Requests whose signature doesn't verify against the webhook secret are rejected, so a wrong value looks like Polar events silently never arriving.

Receive webhooks locally

Polar can't reach http://web.<slug>.localhost, so the local webhook arrives through Tailscale Funnel. Funnel makes apps/web public at your machine's fixed https://<machine>.<tailnet>.ts.net, so you register the endpoint once. Purchases still sync without it, but Polar can't deliver while Funnel is off. It drops each event after 10 failed attempts, and disables the endpoint after 10 failed events in a row. Before a run with Funnel on, re-enable the endpoint in Polar's webhook settings if Polar disabled it, and redeliver the events you need.

  1. Set up Tailscale once, as Receive Polar webhooks locally describes.
  2. Start the app with Funnel on for this run:
    Terminal
    PORTLESS_FUNNEL=1 pnpm dev:web
    
  3. In the <slug>-web-local organization, point the webhook at https://<machine>.<tailnet>.ts.net/api/webhooks/polar. portless prints the URL when it starts.

Funnel stays off unless you set PORTLESS_FUNNEL=1, and pnpm dev:site is never made public. No other tunnel is supported: the dev command switches portless's other tunnels off.

Only one checkout receives webhooks at a time. The endpoint names Funnel's port 443, and a server on another port would receive nothing. So the dev command stops when another server already holds 443. Stop that server's Funnel first. Webhooks that reach the wrong checkout fail against its database, and Polar disables an endpoint whose deliveries keep failing.

Next steps

Copyright © 2026