Troubleshoot widget identify

Fix widget identify problems: what each error code means, why tokens fail, why Submit is disabled, email changes, and FAQs about the signing secret and teammates.

Use this article when signed-in users are not recognized in the widget, when an identify call fails, or when the Submit button stays disabled. It lists the identify error codes, common causes, and answers to frequent questions about the signing secret and teammates.

Check what identify returned

Listen for the identify event to see whether identification worked and why it failed:

Quackback("on", "identify", (payload) => {
  if (!payload.success) console.error("Identify failed:", payload.error);
});

You can also call Quackback.isIdentified() or Quackback.getUser() after identify completes.

Error codes

Code	What it means	What to do
`VALIDATION_ERROR`	The request had no `ssoToken`. This is what happens when you pass `{ id, email, name }` from the browser.	Sign a JWT on your server and call `identify({ ssoToken })`. Unsigned user details are always rejected.
`TOKEN_INVALID`	The token's signature did not match, the token expired, or it is missing the `sub` (or `id`) and `email` claims.	Sign with HS256 using the current signing secret from Settings > Widget > Install. Include `sub` and `email`, and mint a fresh token (about 5 minutes) on each page load.
`EMAIL_IN_USE`	The token's `sub` belongs to one account, but its `email` is already used by a different account.	Check that your app sends a stable `sub` per user and the right email. Look up which account holds that email in Admin > Users.
`WIDGET_DISABLED`	The widget is turned off.	Turn on Show on your website in Settings > Widget.
`SERVER_ERROR`	Often means the workspace has no signing secret yet.	Open Settings > Widget > Install and reveal the signing secret. That creates one if none exists.
`RATE_LIMITED`	Too many identify attempts from one address in a short time.	Call identify once per session, not on every render or navigation. Wait and try again.
`BLOCKED`	This person has been blocked by your team.	Unblock them in Admin > Users if the block was a mistake.
`NETWORK_ERROR`	The widget could not reach your Quackback workspace.	Check network access to your workspace URL and any content security policy on your site.

The token keeps failing

Wrong secret. The secret in your app must match the one in Settings > Widget > Install. If someone clicked Regenerate, the old secret stopped working immediately: update your app's environment variable and redeploy.
Expired token. Tokens are short-lived on purpose. Fetch a new one when the page loads instead of caching it.
Wrong algorithm. Use HS256.
Secret in the wrong place. The secret belongs in your app's server environment under any name. Setting it on your Quackback server does nothing.

The Submit button is disabled

The Feedback tab enables Submit only when the current visitor may post on the selected board.

Is the visitor actually identified? If identify failed, they are anonymous. Check the identify event first.
Does the board allow this visitor to submit? Each board's access settings decide who can submit. A signed-in user without access sees "You don't have access to post on this board". See Organize feedback with boards.
Is anonymous interaction off? When Allow anonymous interaction is off (in Settings > Access & Security > Portal access), every board requires sign-in to post, vote, or comment, so anonymous visitors cannot submit.
Is the Feedback module on? If Feedback & Roadmaps is off in Settings > General, the widget has no Feedback tab.

The user's email changed

sub is the durable key. When a user's email changes in your app and you identify them with the same sub, Quackback updates the account to the new email. If another account already uses that email, identify fails with EMAIL_IN_USE.

If you removed a user from your workspace and they identify again later, Quackback creates a fresh account for them.

Frequently asked questions

Where do I get the signing secret?

The easiest way is the agent install: Settings > Widget > Install > Copy install prompt. Your coding agent fetches the secret with a short-lived pairing code and stores it in your app's server environment. To wire identify by hand, reveal and copy the secret under Signing secret on the same page.

Is the signing secret plan-gated?

No, it is not. Every workspace has a signing secret, and it lives in your app, not in Quackback. Identifying users is available on every plan.

Yes. A teammate identified in the widget is treated as a customer in the widget. This never signs them in to the admin dashboard, and their dashboard name and avatar are not overwritten by your app's token.

Do I need to call logout before switching users?

No, you do not. Call identify again with the new user's token. Call logout when the user signs out of your app.