Legacy approach. For new integrations, use the Widget SDK with Access Key Embed.

Migrating to Access Key Embed

If you are currently using auth-url token auth, here is what changes:

Endpoint: Replace your POST /widget/{id}/signin call with POST /v2/api/widget-access-keys/token.
Attribute: Replace auth-url with embed-token on the widget tag.
Refresh: Legacy auth-url can auto-refresh using refresh tokens. Access Key Embed does not call your backend for a new embed-token; re-render or reload with a fresh token when needed.

See the Access Key guide for the full walkthrough.

Auth - Token

Sign users in server-side so the widget loads pre-authenticated. The user never sees a login screen - the token is fetched behind the scenes before the widget renders.

Attribute auth vs token auth

	Attribute authentication	Token authentication
User identity	Client-side via data-* attributes (email, userId, etc.)	Server-verified via API key
Backend required	No	Yes
Token flow	None - attributes passed directly	Your backend calls Returning.AI, returns a short-lived token
User experience	Seamless - user identified by attributes	Seamless - already signed in
Best for	Quick integrations, internal tools, controlled environments	Logged-in areas, client portals, trader dashboards

Step 1 - Create a backend endpoint

Your server calls the Returning.AI sign-in API with your secret API key and the current user's email. It receives a short-lived token that the SDK will use to authenticate the widget session.

Keep your API key server-side

Never expose WIDGET_API_KEY in client-side code. It should only exist in environment variables on your backend.

server.js

app.post('/api/widget-auth', async (req, res) => {
  const response = await fetch(
    'https://prod-widgets.returning.ai/widget/{community_id}/signin',
    {
      method: 'POST',
      headers: {
        'returningai-api-key': process.env.WIDGET_API_KEY,
        'email': req.user.email,
        'Content-Type': 'application/json',
      },
    }
  )
  const data = await response.json()
  res.json({ token: data.token })
})

Step 2 - Point the widget to your endpoint

Add the auth-url attribute to your widget tag. The SDK will POST to that URL on load, receive the token, and authenticate automatically.

<rai-channel-widget
  community-id="YOUR_COMMUNITY_ID"
  api-url="https://prod-widgets.returning.ai"
  widget-url="YOUR_WIDGET_URL"
  auth-url="/api/widget-auth"
></rai-channel-widget>

How the flow works

Widget mounts and detects the auth-url attribute.
SDK sends a POST request to your backend endpoint.
Your backend verifies the user and calls the Returning.AI sign-in API.
Your backend returns the token to the SDK.
SDK passes the token into the widget iframe - the user is signed in.

Token expiry and refresh

Tokens are short-lived (typically around 5 minutes). The SDK handles renewal automatically - when a token is about to expire, it re-calls your auth-url endpoint to fetch a fresh one. No extra code is needed on your side.

If the refresh fails (e.g. the user's session has expired on your backend), the widget fires an rai-error event that you can listen for to prompt re-authentication.