Authentication

Two ways to identify users in Returning.AI widgets. Both are legitimate strategies with different tradeoffs.

Two Methods

Attribute Authentication

Pass user identity directly via HTML attributes (data-email, data-userId, etc.) or URL query parameters. No backend required. Security through stacking: the more attributes you add, the harder to spoof. Can include custom fields for additional security layers.

Token Authentication

Your backend calls Returning.AI's signin endpoint with your API key and the user's email. It receives a short-lived token that the widget uses for authenticated API calls. The API key never touches the client.

How Token Auth Works

The token authentication flow follows a four-step process:

1
Your backend authenticates the user
The user logs in through your existing authentication system (session, JWT, OAuth, etc.).
2
Your backend calls the Returning.AI signin endpoint
Your server sends a POST request to https://prod-widgets.returning.ai/widget/{community_id}/signin with the user's email and your API key in the headers.
3
Returning.AI returns a session token
The API responds with a short-lived token that identifies the user session.
4
The token is passed to the widget
For the Widget SDK, this happens automatically via the auth-url attribute. For iframe embeds, the token is exchanged via postMessage. For server proxy, the token is injected into the HTML server-side.

server.js

// Simplified token auth flow (Node.js backend)
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 })
})

Token Lifecycle

Session tokens are short-lived and will expire. How token refresh is handled depends on your integration method:

Method	Token Refresh
Widget SDK	Automatic. The SDK monitors token expiry and re-calls your `auth-url` endpoint to refresh.
Iframe Embed	Manual. The widget iframe sends a `RETURNINGAI_WIDGET_REQUEST_TOKEN` postMessage when the token expires. Your page must listen for this event and respond with a fresh token.
Server Proxy	Server-managed. Your backend fetches a new token on each page load or when the cached token expires.

Security

Both methods are valid authentication strategies. Choose based on your requirements:

	Attribute Auth	Token Auth
Backend required	No	Yes
API key exposure	Not applicable	Server-side only
Identity verification	Client-provided attributes	Server-verified via API key
Spoofing resistance	Increases with more stacked attributes	High (server-side verification)

Never expose your API key

When using token authentication, never include your API key in client-side code. Always use a server-side proxy endpoint. If your key is compromised, rotate it immediately from the Returning.AI admin panel.

Choosing Between Them

•Use attribute auth when you need a quick integration, have no backend, or are in a controlled environment where you trust client-side identity.
•Use token auth when you need server-verified identity, handle sensitive user data, or operate in a public-facing environment where spoofing is a concern.

Implementation Guides

Choose the guide that matches your integration method:

Widget SDK - Attribute Auth

Pass identity via data-* attributes on the widget element.

Widget SDK - Token Auth

Use the auth-url attribute for automatic token management.

Iframe - Attribute Auth

Pass identity via URL query parameters on the iframe source.

Iframe - Token Auth

Use postMessage to exchange tokens between your page and the widget iframe.