JamAuth setup — Netlify

▋jamauth Setup

Register your site
In progress

Enter the exact origin where your deployed site is running, then choose the first login and protected paths.

Deployed site origin
The public base address of the site you’re protecting. Include https://, but no page path or trailing slash. Example: https://your-site.netlify.app

For the fields below, enter a path beginning with / — not your full domain.

Login path
The page on your site that contains the JamAuth login form.

First page to protect
The first page or route visitors must sign in to view. You can protect more later.

Callback path
The server endpoint that completes magic-link login. JamAuth supplies it; visitors do not open it directly.

How these fit together

Your site origin + a path = the complete page address.

Login page https://your-site.netlify.app/login.html

Protected page https://your-site.netlify.app/protected

How paths work

Paths always begin with a single / — do not paste your full domain into a path field.

The deployed origin must be the production HTTPS origin registered with JamAuth. A Netlify preview-deploy URL or localhost is not a substitute for that registered production origin.

Local Netlify Dev behavior is covered later, during configuration and verification.

Your first login flow
Choose who gets access
Locked

Select the rule that grants access
Add the email address you will use for the first login test. Only addresses on this list can complete login while Approved Emails is active.

Owning the JamAuth project does not automatically grant access to the protected site.

Loading access settings…

Email to approve
No approved emails yet.
Add the email you will use to test login.
Next: add the login form to your site.
Add login
Locked

Put the login form on your site
Create this login page in your Netlify publish directory. It loads the JamAuth widget and sends the user back to the protected path after login completes.

The magic link can be requested from this page, but the login cannot complete end to end until you add the callback in Step 4.

Login URL

File path inside your Netlify publish directory

Public Client ID

Default protected destination

Canonical widget URL
Generated login page
JamAuth cannot see your repository. Mark this complete after you add the generated file. Step 7 will verify the deployed login flow.
Add callback
Locked

Exchange the magic link for a session
Add these two Netlify functions. The callback completes the magic-link exchange and sets the first-party session cookie. The session function lets the login widget check that cookie.

Step 6 will add the required environment values and deploy the functions.

Loading callback and session source…

Registered callback URL

Callback target path

Session endpoint URL

Session target path

Canonical JamAuth host

Public Client ID

Required later (Step 6)

Create these files in your Netlify functions directory. If your netlify.toml configures a custom functions directory, place these files there using the shown filenames.
Purpose
Completes the magic-link exchange and sets the first-party session cookie.

Target path
Callback function source
Purpose
Reads the session cookie and calls JamAuth refresh-session for the widget.

Target path
Session function source
JamAuth cannot see your repository. Mark this complete after you add both files. Step 6 will configure and deploy them; Step 7 will verify the live flow.
Protect your page
Locked

Require that session before serving content
Add this server-side function. It checks the JamAuth session before returning any protected content.

This function returns a protected starter page. Step 6 will route your configured protected URL to it. After verification, replace the response template with your content or adapt the verified-session block to your server route.

Step 6 will configure the required environment values, route, and deployment.

Loading gate function source…

Configured protected URL

Configured login URL

Gate function endpoint URL

Gate target path

Public Client ID

Canonical JamAuth host

Required later (Step 6) environment values
Purpose
Checks the JamAuth session with refresh-session before returning protected content.

Target path

Create this file in your Netlify functions directory. If netlify.toml uses a custom functions directory, place protected-page.js there.
Protected-page function source
JamAuth cannot see your repository. Mark this complete after you add the function. Step 6 will configure the route, environment values, and deployment; Step 7 will verify that the protected URL fails closed.
Configure and deploy
Locked

Add environment values and route mappings
Set the production environment values, merge the protected-route rewrite, and deploy to your registered origin. JamAuth cannot inspect your repository, change your Netlify settings, or deploy for you.
Registered production origin
Production environment values
Set these in Netlify’s environment-variable settings (Project configuration → Environment variables) or with the CLI below, scoped to Functions and the Production context. Do not commit this block merely because it uses .env formatting — none of these five values is a client secret, but they still should not be committed to your repository.
Testing on plain HTTP localhost?

Production stays on __Host-jam_session — the callback sets that cookie with Secure, and plain HTTP localhost cannot use it as a normal browser session. For local HTTP function testing only, you may use a non-prefixed local value instead, supplied consistently to the callback, session, and gate functions. This does not change your registered production origin, and a local smoke test is not Step 7 verification.
Netlify CLI
Run from the customer site repository.
Netlify CLI commands (preferred, Functions scope)
Review each command before running it. These set the five values above, scoped to Functions, in the Production context, and list them back for verification. No command links or relinks a site, imports with a destructive replace flag, or executes automatically.
Environment-variable scopes unavailable on your plan?

Per-scope environment-variable controls (like --scope functions above) require a Netlify plan with that feature. JamAuth cannot detect your plan from this page. If your Netlify CLI or dashboard does not offer scope controls, use this fallback instead — it keeps the Production context explicit but omits --scope, so each value becomes available to every scope (builds, functions, runtime, post-processing) rather than only Functions.
Netlify CLI commands (fallback, all scopes)
Protected-route rewrite
Maps your exact configured protected path to the gate function.

netlify.toml _redirects

Use the routing file your site already maintains. Do not replace an existing file; merge the generated rule into it.

A matching _redirects rule always runs before netlify.toml. Netlify processes every rule in the published _redirects file first, then every rule in netlify.toml, and stops at the first match — a netlify.toml rule can never outrank an existing _redirects catch-all, no matter where it is placed inside netlify.toml. If your publish directory already contains a _redirects file with a matching catch-all such as /* /index.html 200, either (A) select the _redirects strategy below and place the JamAuth rule above that catch-all, or (B) remove or narrow the conflicting _redirects rule. Merely placing the JamAuth rule early inside netlify.toml is not sufficient in that case.

Within a single file, put the JamAuth protected-route rule before any broader catch-all rule such as an SPA /* rewrite — Netlify still stops at the first match within each file.

This rule protects the configured route. It does not automatically protect every path beneath it.

JamAuth cannot inspect your repository — check that this rule appears before any broader rule of your own that would also match the protected path, in both files if you have both.
Generated route snippet
Deployment checklist
Login page added inside the publish directory.

Callback and session functions added inside the functions directory.

Protected-page function added inside the functions directory.

Five production environment values set.

Protected-route rewrite merged before conflicting broader rules.

Production deploy completed at the registered origin.
Connected Git deployment. Commit the customer-site files and configuration to its normal production branch, then push so Netlify builds and deploys that branch.

Netlify CLI deployment. Run netlify deploy --prod from the customer site repository. It uses the site’s existing Netlify link/configuration — review the command before running it. This is a production deployment to the registered site, not a draft deploy.

After changing environment values, create a new production deploy so the functions receive the new configuration.

A Netlify draft deploy or deploy-preview URL is not your registered production origin and is not a valid substitute for it — JamAuth origin/callback validation may reject it.
JamAuth cannot inspect your repository, Netlify settings, or deploy from this step. Mark this complete after you set the five production environment values, merge the protected route, and deploy to the registered origin. Step 7 will verify the live flow.
Verify
Locked

Test allowed, denied, and signed-out access
JamAuth cannot fetch your site from its own servers — that would turn a customer-controlled origin into a new server-side fetch target. Instead, run a small self-contained script on your own computer to check the live, deployed HTTP contract, then confirm the real approved-email flow yourself in a private browser window.

Registered production origin

Login URL

Protected verification URL

Callback URL

Session endpoint URL

Public Client ID

Current verification challenge

No client secret is involved in any Step 7 check.

Starting a fresh verification generates a new challenge and clears any imported verifier result, final-URL evidence, and attestations for this attempt.
1. Run live deployment checks
Generated verifier script (jamauth-live-verify.mjs)
Run it from your own computer. It performs public, read-only HTTP checks only. It does not send an email or log in. Review it before running it. Paste only its JSON result below — never paste a magic-link URL or email token into JamAuth setup.
Run command
```
node jamauth-live-verify.mjs
```
Optional capture command
```
node jamauth-live-verify.mjs > jamauth-verification-result.json
```
Paste the verifier JSON result
2. Test an approved email

Passive HTTP checks cannot prove the real email/callback/browser-cookie path — only you can access your mailbox and complete a first-party browser flow.
1. Open the verification URL below in a fresh private/incognito window.
2. Confirm protected content is not shown before login.
3. Confirm the browser redirects to the configured login page.
4. Use an email that is currently approved in Step 2.
5. Open the magic link in the SAME private browser context where it was requested. Using webmail in that private window, or copying the link into that same private window, is acceptable.
6. Do not open the link in a different browser or profile — the PKCE verifier cookie belongs to the browser context that requested the link.
7. Confirm the callback returns to the protected route.
8. Confirm protected content is visible.
9. Confirm the final address still contains the exact verification challenge.
Do not paste the magic-link URL, a token, state, a grant code, a PKCE verifier, a cookie, or an email body anywhere in JamAuth setup.
Private-window verification URL
Opening this link here opens a normal browser tab, not a private window — you must open a fresh private/incognito window yourself.

Paste the final protected-page URL

This is only for the final post-login protected-page address, never the magic-link URL.

I used an email that is approved in Step 2. I completed the magic link in the same private browser context. I saw protected content after the callback returned.
3. Optional: test a denied email

Optional but recommended. Because Approved Emails is your current access mode:
1. Use a separate fresh private browser context.
2. Use an inbox you control that is NOT in the Approved Emails list.
3. The login widget still shows the generic "check your email" response.
4. After clicking the link, JamAuth denies access before the tenant callback.
5. The browser sees the JamAuth-hosted access-denied response.
6. No tenant session cookie is issued.
7. Protected content is not reached.
Do not paste the denied magic-link URL or the complete-login URL anywhere in JamAuth setup.
I also verified that an unapproved email is denied.
4. Finish verification

Live deployment checks, the approved-email evidence, and all three required attestations are needed before you can finish.
Open the protected URL · Back to the JamAuth dashboard

Set up JamAuth for Netlify

Register your site

Site registered

Choose who gets access

Add login

Add callback

Protect your page

Configure and deploy

Verify