How to set up the identity token

    Sign a token on your server and pass it to the widget, so Gruvi takes the visitor's identity from your sign-in.

    5 min read · Updated 27 October 2026

    This is the developer setup behind Require identity verification.

    What the token does

    If your widget sits inside a product people log into, your system already knows who they are. The token passes that identity to Gruvi, signed, so the visitor does not have to type anything.

    Before you start

    • A developer. The work is a change on your server and one line where the widget is installed.
    • A product people log into. There is no identity to pass otherwise.
    • Somewhere to store a secret. The signing secret must stay on your server.

    Step one, get your signing secret

    1. 1Open the chat box, go to the Rules tab, and find Identity verification.
    2. 2Under Signing secret, click Reveal secret.
    3. 3Copy it into your server's environment, for example as GRUVI_IDENTITY_SECRET.

    Step two, sign a token on your server

    Create a token for the signed-in visitor and sign it with that secret. The settings page shows an example you can copy.

    What goes in it
    The visitor's user id, email address and name, as your system holds them.
    How it is signed
    With your signing secret, using HS256.
    How long it lasts
    The example expires after an hour. Sign a new token when a page loads.
    Sign the token on your server. If you sign it in browser code, the secret is visible to anyone who views the page.

    Step three, pass the token to the widget

    1. 1Copy the second snippet from the Rules tab.
    2. 2Replace the placeholder with the token your server signed.
    3. 3Add it to the pages where the chat appears.

    The snippet includes a short buffer that holds the call until the widget has loaded, so the order does not matter.

    The direct link is a chat page we host, so there is no widget on it to pass a token to. Add the token to the end of the link instead, after #t=.

    The page removes it from the address bar as soon as it loads.

    Keeping the secret safe

    Anyone with the signing secret can sign a token for any visitor. Treat it like a password.

    • Store it as an environment variable, not in your repository.
    • Do not send it to the browser.
    • Reveal it only when you need to copy it.

    Was this helpful?