Set up sign-in and payments
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
| Key | Needed for | Goes in |
|---|---|---|
GOOGLE_CLIENT_ID | Google sign-in (@app/layer-auth) | apps/web/.env.<context>, in Git |
GOOGLE_CLIENT_SECRET | Google sign-in (@app/layer-auth) | Your secret store |
GITHUB_CLIENT_ID | GitHub sign-in (@app/layer-auth) | apps/web/.env.<context>, in Git |
GITHUB_CLIENT_SECRET | GitHub sign-in (@app/layer-auth) | Your secret store |
POLAR_ACCESS_TOKEN | Payments (@app/layer-payments) | Your secret store |
POLAR_WEBHOOK_SECRET | Payments (@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.
| Provider | Callback URL |
|---|---|
<origin>/api/auth/callback/google | |
| GitHub | <origin>/api/auth/callback/github |
| Polar | <origin>/api/webhooks/polar (webhook endpoint) |
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 Context | Dashboard | Name and slug | Webhook |
|---|---|---|---|
local | sandbox | <slug>-web-local | Your Funnel URL — see Receive webhooks locally |
development | sandbox | <slug>-web-development | <origin>/api/webhooks/polar |
preview | sandbox | <slug>-web-preview | None — put a stand-in in its POLAR_WEBHOOK_SECRET |
staging | sandbox | <slug>-web-staging | <origin>/api/webhooks/polar |
production | polar.sh | PROJECT_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:
- Sign in to the dashboard the table names. The sandbox keeps its own accounts, so sign up there the first time.
- Select the current organization's name at the bottom of the sidebar, then select New Organization. A new account starts on this form.
- 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:
POLAR_ACCESS_TOKEN— create an organization access token under Settings > Developer. See Polar authentication.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 ofpackages/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.
- Set up Tailscale once, as Receive Polar webhooks locally describes.
- Start the app with Funnel on for this run:Terminal
PORTLESS_FUNNEL=1 pnpm dev:web - In the
<slug>-web-localorganization, point the webhook athttps://<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
- Set up your secret store — where the secret half of each pair goes
- Local setup — the rest of getting the project running
