Auth methods

Prerequisites

• A Modifee project.
• The project Settings page.

The wizard step Client access uses Public site, no login and Site with login. Settings calls the same modes Site without login and App with login. The default is Site without login.

Steps

Open Settings → Client access. The description is "How a client proves who they are before opening the widget." The field is Authentication.

Site without login

Use this when the site has no login. The client proves who they are with an email and a code.

1. Set Authentication to Site without login.
2. Set the access marker and who can request changes.
3. Press Save.

The install snippet has no data-token and does not use MODIFEE_SECRET. The button stays hidden until the client opens the marker URL. Ctrl+Shift+M on the site shows it during setup.

What the client sees, in the widget language (en, fr, es):

1. The launcher. English: "Request a change".
2. Enter your email, then Continue.
3. An email whose subject is "Your Modifee code:" plus the code. The body says "This code expires in 10 minutes."
4. Enter the code you received, then Verify.
5. The request screen. Sign out ends the session. A session lasts 30 days.

App with login

Use this when the site already has accounts. The server signs the logged-in user's email. Guests do not get a token, so they do not see the widget. There is no email step.

1. Set Authentication to App with login.
2. Press Save. Signing secret appears under the card.
3. Install the signed snippet. See Next.js App Router, Next.js Pages Router, or Other frameworks.

The token is the base64url JSON { email, name, exp }, a ., then the base64url HMAC-SHA256 of that base64url string. exp is the unix time plus 86400 seconds (24 hours). The HMAC key is MODIFEE_SECRET. The same shape is in the install library:

// Your server must generate the token; never put the secret in the browser.
// payload = base64url(JSON { email, name, exp })
// token = payload + "." + base64url(HMAC_SHA256(MODIFEE_SECRET, payload))

<script src="https://www.modifee.com/widget.js" data-project="YOUR_PROJECT_KEY" data-token="TOKEN" async></script>

Replace TOKEN with that signature. email is required. name may be omitted. The widget reads data-token from the script tag. It does not call your server for the token.

MODIFEE_SECRET is the project key secret. Settings → Client access → Signing secret shows it in the code block labeled MODIFEE_SECRET. Modifee stores it encrypted. On the host it is the environment variable MODIFEE_SECRET, read only in server code (process.env.MODIFEE_SECRET in the Node snippet). On Vercel it is pushed for Production and Preview. See Signing secret.

The browser receives the token only. Put the secret in the server environment. A NEXT_PUBLIC_ variable, a client bundle, or the HTML of a guest page would let anyone sign a token for an allowed email.

The page that renders the token must be built per request and must not be cached. See the App with login section of the install page for that framework.

Verify

1. Press Save on Client access.
2. The mark beside Client access is green when at least one email or domain is saved. For App with login it also waits until a Vercel project is linked and MODIFEE_SECRET has been pushed. See Allowed emails and Signing secret.
3. Open the site the way a client would. Site without login: the marker URL, then the email and the code. App with login: a signed-in page, with the widget and no email prompt.

Troubleshooting

• "Choose how clients open the widget."
• Yellow Client access, tooltip "No authorized email".
• Yellow Client access, tooltip "Link a Vercel project so the HMAC secret can be pushed".
• Yellow Client access, tooltip "HMAC secret is not on Vercel yet".
• "MODIFEE_SECRET is only used for App with login."
• "MODIFEE_SECRET is not set" when the generated signing function runs without the variable.
• Browser console: "Modifee: data-project and data-token are required".
• "Could not verify your identity. Refresh the page and try again." is MDF-AUTH-001.
• "That code is incorrect or has expired." is MDF-AUTH-004.
• "Too many attempts. Request a new code." is MDF-AUTH-005.
• "Too many codes requested. Try again in a few minutes." is MDF-QUOTA-003.
• "This email isn't allowed to request changes on this site." is MDF-AUTH-002. See Allowed emails.