Connect

Visitor sign-in

Verify who the visitor is on your platform before the AI calls any secure custom tool. Required for “What’s my balance?”, “Show my order”, “Cancel my subscription” — anything tied to a specific user account. Public tools (“track this package by tracking number”) work without sign-in.

When you need this

Two example flows side-by-side:

How it works (architecture)

1. Visitor signs in on your platform via your existing flow (email/password, SSO, Google, whatever).
2. Your platform produces a signed token proving who the visitor is — either a standard JWT signed with public-key crypto (recommended) or a JWT signed with a shared HMAC secret.
3. Your page calls ChatWidget.identify({ token }) after sign-in. The widget attaches the token to every chat request.
4. Our chat backend verifies the token against the keys you registered on the Visitor sign-in config page.
5. Verified identity is attached to the request context. Any custom tool marked “requires sign-in” can now run and gets the verified user id automatically.

We never store your visitor passwords. We only verify a token your auth system already issued.

Mode 1 — JWT + JWKS (recommended)

Your platform issues JWTs and exposes a JWKS endpoint with the public keys. We pull the keys, cache them for 15 minutes, and verify token signatures locally on every chat request.

You configure this on the Visitor sign-in page (Integrations → Back to Integrations links back to it). In the panel below, the top Mode card is a single choice — Disabled, JWT + JWKS, or HMAC shared secret. Picking JWT + JWKS reveals the JWKS endpoint card, where the one required field is the JWKS URL. The optional Required claims card below it (Issuer / Audience) and Claim mapping are covered later on this page. Click Save at the bottom to store it.

Auth0 example

1. In our dashboard: Integrations → Visitor sign-in → JWT + JWKS.
2. JWKS URL: https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json
3. Issuer (optional): https://YOUR_DOMAIN.auth0.com/
4. Audience (optional): the API identifier you set up in Auth0.
5. Save.

On your page, after Auth0 login completes:

const auth0 = await createAuth0Client({ ... });
const token = await auth0.getTokenSilently();
ChatWidget.identify({ token });

Amazon Cognito example

Use the User Pool ID’s discovery doc — Cognito serves a standards-compliant JWKS at:

https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}/.well-known/jwks.json

Issuer: https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}.

Clerk / Firebase Auth / generic OIDC

Same pattern. Any provider that serves a JWKS works. Common endpoints:

• Clerk: https://your-app.clerk.accounts.dev/.well-known/jwks.json
• Firebase: https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com (different format — we accept it)
• Generic OIDC: append /.well-known/jwks.json to your issuer URL.

Key rotation

Keys cache for 15 min. After you rotate keys, click the “Refresh JWKS + verify” button on the Test card to force an immediate refresh. Production traffic refreshes automatically on the next chat request after the cache expires.

Mode 2 — HMAC shared secret

Simpler if you don’t already have public-key infrastructure. Your backend signs a JWT with HS256 + a shared secret we store encrypted at rest. Less recommended than JWT/JWKS only because a leaked secret is a one-step path to forged identities — rotate it if you suspect compromise.

Setup

Pick HMAC shared secret in the Mode card and the Shared secret card appears. In the panel below, the Generate button next to the Secret field creates a random 32-byte value (base64) — copy it into your backend’s secrets manager and sign your JWTs with it using HS256. Once a secret is stored, the card shows a green Secret is configured (hidden) row with a Clear button, and the field re-labels to Replace secret so you can rotate it without ever seeing the old value (we never echo it back). The example sign code under the field is the exact jose call your backend runs. Save to store it encrypted at rest.

1. In our dashboard: Integrations → Visitor sign-in → HMAC shared secret.
2. Click Generate to create a random 32-byte secret. Copy it to your backend’s secrets manager.
3. Save.

Node example (sign in your backend)

Use the same jose library we use for verification:

import { SignJWT } from "jose";

const secret = new TextEncoder().encode(process.env.QUINCER_VISITOR_SECRET);

// Call this after your user signs in.
async function tokenForUser(user) {
  return new SignJWT({
    email: user.email,
    name: user.name,
    plan: user.plan,
  })
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(user.id)          // → ends up as the canonical user id
    .setIssuedAt()
    .setExpirationTime("1h")       // short-lived; rotate on refresh
    .sign(secret);
}

Pass the token to the widget

On the page where your user lands after signing in:

<script>
  // Server-rendered: include the token in your HTML response.
  ChatWidget.identify({ token: "{{ JWT_FROM_BACKEND }}" });
</script>

Or fetch the token from your own /api/me/quincer-token endpoint after sign-in.

Popup sign-in flow (optional)

If you want the widget itself to prompt the visitor to sign in when a secure tool is needed, register a Sign-in URL in the config. The widget opens this URL in a new tab when an unauthenticated visitor asks for a secure tool; your sign-in page posts the token back when login succeeds.

Your sign-in page

// after login completes:
const token = await getQuincerTokenForCurrentUser();
window.opener.postMessage(
  { type: "quincer-identify", token },
  // Match the origin where the widget is embedded.
  "https://your-customer-site.com"
);
window.close();

The widget verifies the message origin matches the configured Sign-in URL before accepting the token, so a random tab can’t inject one.

Claim mapping

The model only sees what you tell it to see. The verifier extracts standard JWT claims by default (everything except iss/sub/aud/exp/iat/nbf/jti) and passes them to tools that need identity. To rename or restrict that, fill in the Claim mapping JSON. Example:

{
  "userId": "sub",
  "email": "email",
  "tier": "https://acme.example/tier",
  "accountId": "https://acme.example/account_id"
}

Now a custom tool that lists requiredClaims: ["userId", "tier"] works as expected, even though the JWT uses Auth0’s namespaced custom-claim convention.

Testing your setup

The config page has a built-in Test a token card:

In the panel below, paste a real token into the box and click Verify. In JWT mode a second Refresh JWKS + verify button drops the cached keys and refetches before verifying — use it right after rotating keys. A pass renders a green Verified result showing the resolved sub, the source (jwt or hmac), and the exact Claims the AI tools will see; a failure shows the reason and message instead.

1. Sign in on your platform and grab a real token (browser dev tools, your backend, your auth provider’s dashboard).
2. Paste it into the Test card and click Verify.
3. You’ll see either a green “Verified” result with the resolved identity (this is what the AI tools see), or a clear failure reason and message.

Use this to iterate on the JWKS URL, the issuer/audience values, and the claim mapping without bouncing through your full sign-in flow.

Common failure reasons

Security notes

• HMAC secrets are encrypted at rest with the same key-store the rest of your API keys use. We never echo them back in dashboard GETs.
• JWKS responses are cached 15 min — key rotation propagates automatically; the dashboard’s refresh button forces an immediate re-pull.
• The widget’s postMessage listener verifies the origin against the configured Sign-in URL before accepting an identify message.
• Identity is verified per chat request — a forged token can’t survive a single round-trip.
• Logs of verification failures are written to Railway’s console (no token contents, just the reason).