Signing secret

Prerequisites

• Settings → Client access → Authentication set to App with login, then Save. Signing secret is hidden for Site without login.
• An API key for the project. Settings → Danger zone shows "No active key." until one exists. Projects get a key when they are created.

See Auth methods for the token shape. The host reads the variable in server code only.

Steps

Open Settings → Client access → Signing secret.

The code block is labeled MODIFEE_SECRET. That value is the project key secret. The agency app signs the logged-in user's email with HMAC-SHA256. The browser receives the token, not this value.

On Vercel

1. Connect Vercel and link the project. The line is "Linked to Vercel project:" and the project name.
2. Linking writes MODIFEE_SECRET for Production and Preview. The status becomes "MODIFEE_SECRET set on Vercel ✓" once the variable is on production. "Last push:" shows the date of that write.
3. That checkmark means the variable is stored. The running deployment still has the previous environment until you redeploy. The banner under the status is the signal. Follow Redeploy.

The sentence under the status is "This is the HMAC secret stored for this project. Regenerating updates Vercel for Production and Preview."

Status lines:

• "MODIFEE_SECRET set on Vercel ✓" — the variable is on production. A redeploy can still be required. See Redeploy.
• "MODIFEE_SECRET is not on Vercel yet."
• "Vercel not connected — connect or add it manually"
• "This project is not linked to a Vercel project."
• "Could not check MODIFEE_SECRET on Vercel."

On another host

When Vercel is not connected, or the project is not linked, the page says "Add this value as the MODIFEE_SECRET environment variable on your host. The agency app signs the logged-in user's email with HMAC-SHA256."

Copy the code block into the server environment. Redeploy that host so the process sees it. Press Connect Vercel when you want the push instead.

Regenerate

Press Regenerate. There is no extra confirm.

What changes:

• Modifee replaces the stored secret immediately. Tokens signed with the previous value fail.
• The code block shows the new value.
• When a Vercel project is linked, Production and Preview are updated to that value. "Last push:" changes. The redeploy banner appears, because the running deployment still has the old value. See Redeploy.
• When no Vercel project is linked, the status is "This project is not linked to a Vercel project." Copy the new value onto the host yourself. The log reason is "project is not linked to a Vercel project", or "workspace has no Vercel connection".
• If the stored secret changed and Vercel rejected the write, the error is "Secret regenerated, but Vercel was not updated." followed by the Vercel message. The host still has the old value until a later push succeeds.

Every install that signs with MODIFEE_SECRET must use the new value. Old HTML that still carries a token signed with the previous secret is rejected.

Verify

1. The code block MODIFEE_SECRET has a value.
2. On Vercel, the status is "MODIFEE_SECRET set on Vercel ✓" with "Last push:". The banner asks for a redeploy until production has deployed since that push.
3. After Redeploy, a signed-in page on the new deployment opens the widget.
4. The mark beside Client access is green for the secret once the push time is stored. An empty allowlist can still leave it yellow. See Allowed emails.

Troubleshooting

• "This project has no API key yet."
• "Generate an API key before setting MODIFEE_SECRET."
• "Generate an API key before regenerating the signing secret."
• "Could not read this project's secret."
• "MODIFEE_SECRET is only used for App with login."
• "Link a Vercel project before setting MODIFEE_SECRET."
• "This project is not linked to a Vercel project we can update."
• "MODIFEE_SECRET already exists on Vercel."
• "Vercel refused to set MODIFEE_SECRET."
• "Could not reach Vercel."
• "Secret regenerated, but Vercel was not updated."
• "The Vercel integration cannot read or write environment variables. Add the Environment Variables permission on the Modifee integration, then reconnect Vercel."
• "The Modifee Vercel integration is missing the Projects read-write scope."
• 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".
• The widget loads and then says "Could not verify your identity. Refresh the page and try again." The deployment is still signing with the previous secret, or the token is older than 24 hours. Redeploy, then sign in again. MDF-AUTH-001. Secret and redeploy.