Identify Signed-in Visitors

Identify Signed-in Visitors#

When a shopper or member is signed in to your site, your chatbot can answer questions only that person should see — “where is my order?”, “what’s on my account?” — without asking them to prove who they are again. To do that safely, your website tells Gydr who is signed in with a short-lived identity token that only your server can create.

You need this only if a connected plugin looks up personal data (for example WooCommerce order status). A chatbot that only answers general questions works without it.

How the token works#

1. You create an identity key in Console → Settings → Identity verification. The key has an id (the kid, e.g. idk_7Qm2) and a secret. The secret is shown once — store it in your server’s configuration.
2. When a visitor is signed in, your server signs a small JSON Web Token (JWT, HS256) with that secret, naming the user and your Gydr account.
3. The widget fetches the token from your site, keeps it in memory, and sends it with each chat message. It never puts it in a URL or in browser storage.
4. Gydr checks the signature, the account and the expiry. A valid token proves who the visitor is; anything else is treated as a guest.

The token#

A standard JWT: a header, a payload of claims, and a signature.

{ "alg": "HS256", "typ": "JWT", "kid": "idk_7Qm2" }

{
  "sub": "42",
  "aud": "<your Gydr account id>",
  "iat": 1790000000,
  "exp": 1790003600,
  "email": "siti@example.com",
  "email_verified": false,
  "name": "Siti Rahman",
  "attrs": { "crm_id": "c_91" }
}

Claims#

Sign the token on your server#

Keep the account id, key id and secret in server configuration (environment variables, a secrets manager, wp-config.php).

// npm install jsonwebtoken
import jwt from 'jsonwebtoken';

export function gydrIdentityToken(user) {
  return jwt.sign(
    {
      sub: String(user.id),
      aud: process.env.GYDR_ACCOUNT_ID,
      name: user.name,
      email: user.email,
      email_verified: user.emailVerified === true,
    },
    process.env.GYDR_IDENTITY_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: '1h', // sets exp; iat is added automatically
      header: { kid: process.env.GYDR_IDENTITY_KID },
    },
  );
}

Give the widget a token endpoint (recommended)#

Add one URL on your own site that returns the current visitor’s token, and point the widget at it with data-identity-endpoint. The widget calls it itself — with the visitor’s cookies, never cached — before the first message and again whenever the token is under a minute from expiring.

<script
  src="https://cdn.gydr.ai/widget.js"
  data-api-key="pk_live_YOUR_KEY"
  data-identity-endpoint="/gydr/identity-token"
  async
></script>

• The endpoint must be on the same site (same origin) as the page. A path like /gydr/identity-token is simplest.
• Return { "token": null } for a guest. An error status or a network failure changes nothing — the widget keeps what it has and tries again shortly, so a blip never signs anyone out.
• Never let a page cache or CDN store this response — it belongs to one person.

Or supply the token from JavaScript#

For a single-page app or a site where a plain endpoint doesn’t fit, register a function with Gydr.setIdentityTokenProvider(). Register it from the script tag’s load event so it is in place before the first message. Return the token, or null when nobody is signed in. Throw on errors instead of returning null — null means “signed out” and clears the conversation.

const script = document.createElement('script');
script.src = 'https://cdn.gydr.ai/widget.js';
script.dataset.apiKey = 'pk_live_YOUR_KEY';
script.async = true;
script.addEventListener('load', () => {
  window.Gydr.setIdentityTokenProvider(async () => {
    const res = await fetch('/api/gydr-token', { credentials: 'same-origin', cache: 'no-store' });
    if (!res.ok) throw new Error('token unavailable'); // keeps the current state
    const { token } = await res.json();
    return token; // a string, or null for a guest
  });
});
document.head.appendChild(script);

A site with no way to refresh can pass a fixed token with Gydr.identify({ identityToken }) or the data-identity-token attribute. It stops working when it expires, so prefer the endpoint. All options are listed in the JavaScript API and Data Attributes references.

Sign-out is automatic#

You don’t need to tell the widget when someone signs out. It starts a fresh visitor and a new, empty conversation when:

• your endpoint or provider returns null;
• a token was active and now none is supplied;
• the token names a different person (a different sub).

A conversation that began signed in continues only for that same person — if someone else signs in on the same browser, it is cleared. A signed-in person’s past chats are shown only while they are signed in, and conversations that showed an order are never listed in past chats. Gydr.reset() still clears everything on demand.

Test a token in the Console#

Console → Settings → Identity verification has a tester. Paste a token your server produced; it tells you whether Gydr accepts it and, if not, why (see Troubleshooting). Then open your site signed in, ask the chatbot something personal (“where is my order?”), and ask again signed out.

Rotate a key without signing anyone out#

An account can have two active keys at once, so you can switch without a gap:

1. Create a second key in the Console.
2. Deploy its kid and secret to your server; new tokens are signed with it.
3. Once the old tokens have expired (1 hour if you follow the recommendation), retire the first key.

A lost secret can’t be shown again — create a new key and retire the old one. If you think a secret leaked, rotate immediately.

Troubleshooting#

Each reason the Console tester reports, and the fix:

Next: Guests & data never to send · WordPress & WooCommerce setup