User auth (JWT)

Identify the logged-in user to personalize answers and authorize sensitive actions.

≈ 7 min read

Why?

Without a token, the widget stays anonymous. With a user_token signed by your backend, Guidia knows the identity, role and locale of the user, and can authorize native actions marked requires_user_token.

Architecture

Get the user_token_secret from the console (App → Security → Regenerate).
Your backend signs an HS256 JWT with this secret after authenticating the user.
You pass the JWT to the widget via data-user-token or window.guidia.setUserToken(...).
The widget sends it to /widget/bootstrap which verifies the signature.
On every sensitive action, the live router re-verifies the JWT.

Sign in Node.js

javascript

import { issueUserToken } from "@guidia/sdk";

const token = issueUserToken({
  secret: process.env.GUIDIA_USER_TOKEN_SECRET,
  appId: process.env.GUIDIA_APP_ID,
  tenantId: process.env.GUIDIA_TENANT_ID,
  sub: user.id,
  role: user.role,
  email: user.email,
  locale: user.locale,
  ttlSeconds: 900
});

res.json({ guidia_user_token: token });

Sign in Python

python

from guidia_sdk import issue_user_token

token = issue_user_token(
    secret=os.environ["GUIDIA_USER_TOKEN_SECRET"],
    app_id=os.environ["GUIDIA_APP_ID"],
    tenant_id=os.environ["GUIDIA_TENANT_ID"],
    sub=user.id,
    role=user.role,
    email=user.email,
    locale=user.locale,
    ttl_seconds=900,
)

return {"guidia_user_token": token}

Propagate to the client

html

<script
  src="https://share.guidia.dev/loader.js"
  data-widget-token="WT_..."
  data-app-id="APP_..."
  data-user-token="eyJhbGciOiJIUzI1NiIsImtpZCI6Imd1aWRpYS51c2VyLnYxIn0..."
  async
></script>

To refresh the token without reloading, call window.guidia.setUserToken(newToken). The next bootstrap will carry the new JWT.

NEVER put user_token_secret in front-end code. It must stay server-side only. Regenerate it immediately if leaked.