Identity Verification

Authenticate users in your widget

Identity verification lets your agent know who the user is — enabling personalized support and persistent conversations.

What You Get

Feature	Anonymous	Verified
Chat	Yes	Yes
Conversation history	No	Yes
Personalized by name	No	Yes
User-specific actions	No	Yes

How It Works

1. User logs into your app
2. Your backend mints an Ourguide identity token (JWT signed with your Ourguide secret)
3. Your frontend calls window.ourguide('identify', { token })
4. Widget now knows who the user is

This is not your app’s session JWT. It’s a separate Ourguide-scoped identity token that your backend mints specifically for Ourguide. Your app JWT stays private.

---

1. Get Your Secret

Go to dashboard.ourguide.ai/dashboard/deploy/widget → copy Verification Secret.

Add to your backend environment:

OURGUIDE_VERIFICATION_SECRET=your_secret_here

Never expose this secret in frontend code.

2. Create Backend Endpoint

Node.js (Express)

const jwt = require('jsonwebtoken');

app.get('/api/ourguide-token', authMiddleware, (req, res) => {
  const token = jwt.sign(
    {
      user_id: String(req.user.id),
      exp: Math.floor(Date.now() / 1000) + 3600,
      email: req.user.email,
      name: req.user.name,
    },
    process.env.OURGUIDE_VERIFICATION_SECRET,
    { algorithm: 'HS256' }
  );
  res.json({ token });
});

JWT Payload

Field	Type	Required	Description
user_id	string	Yes	Unique user identifier
exp	number	Yes	Expiration (Unix timestamp)
email	string	No	User’s email
name	string	No	Display name

3. Identify in Frontend

React SDK (Recommended)

import { OurguideWidget } from "@ourguide-ai/ui";

function App() {
  return (
    <OurguideWidget
      productId="YOUR_PRODUCT_ID"
      apiUrl="https://dashboard.ourguide.ai"
      getIdentityToken={async () => {
        const res = await fetch('/api/ourguide-token');
        const { token } = await res.json();
        return token;
      }}
    />
  );
}

With the React SDK, pass getIdentityToken to the widget component. The SDK calls it on mount and auto-refreshes when the token expires — no manual polling needed.

That’s it. No useEffect, no setInterval, no window.ourguide('identify') calls.

4. Handle Logout

React SDK

// Logout is handled automatically — when the component unmounts
// or the user navigates away, the session is cleared.

---

Troubleshooting

Issue	Solution
User not identified	Check secret matches dashboard, user_id is a string
Token invalid	Check exp is in the future, algorithm is HS256
History not persisting	Call identify() on page load, not just after login