Returning.AIDocs
v1

Guides / Legacy

.md

Authentication

For new personalized widgets, use Access Key Embed with your existing backend and login. Legacy authentication is an exception that Returning.AI must explicitly approve for your supplied setup.

Two approaches

Access Key Embed

Your backend selects identity from its trusted signed-in session and exchanges the access ID and secret key for a short-lived signed token. Only that token reaches the widget as embed-token. Do not let a browser request choose the identity your server signs.

Setup-approved legacy authentication

Attribute authentication passes identity in browser attributes. Not having backend access does not make it an equivalent security model or grant approval to use it. Confirm both the allowed method and who supplies identity/session wiring before using the legacy guide.

If you only need a public campaign, a configured open banner may fit. It does not provide the same experience as a personalized rewards widget. Use the integration chooser to separate these paths.

How Access Key Embed works

  1. Collect the approved setup. Returning.AI supplies access credentials, the widget ID and matching bundle URL, identity mapping and allowed origin. Your authorized administrator or setup contact confirms access; do not assume every developer account can change it.
  2. Resolve and verify the user. Your backend uses the host login and the membership gate. Record existence alone is not proof of usable community membership.
  3. Exchange credentials server-side. Your backend calls POST https://api-v2.returning.ai/v2/api/widget-access-keys/token with accessId, accessKey and the configured userIdentifiers. Use the supplied host for a dedicated environment.
  4. Return the short-lived token. Read data.embedToken and data.expiresIn. Your protected route returns only the browser contract, with non-cacheable responses; the custom element receives embed-token.

Use the complete Node.js, PHP or Python server examples and framework-independent quickstart. They include failure handling and trusted-session boundaries rather than a partial token-fetch snippet.

Token lifecycle

Embed tokens expire after 15 minutes. A page can stay open beyond that, whether it was server-rendered or loaded through client navigation. The host must obtain fresh tokens from its trusted current session.

  • With the documented SDK 1.8.11, update embed-token on the current widget and handle rai-session-expired through the shared lifecycle. Do not renew after a terminal authentication failure unless the host explicitly retries or establishes a new session.
  • Follow the current token refresh guide. Its older-build reload fallback is not an instruction to call a global reload on every error.
  • On host logout or account switch, remove the previous user's widget immediately and invalidate pending work. A late token response must not recreate that old view.
  • Token renewal is not proof of refreshed quest progress or rewards. Verify saved state and the supplied bundle's display behavior separately.

Issuance, token validation and widget sessions are separate

Stopping new tokens or clearing the browser does not prove that an already-issued token or downstream widget session has ended. The embed token's expiry does not establish the lifetime of another session. Confirm the supplied environment's termination behavior before security approval, using the handover decision gates.

Comparison

QuestionAccess Key EmbedLegacy attribute authentication
Who selects identity?Your trusted backend session, signed into a token.Browser attributes; your setup must approve this trust model.
What reaches the browser?The short-lived token and readable signed claims, never the secret access key.The supplied identity attributes and public configuration.
Who needs backend access?Your engineering team supplies the protected token endpoint.A paste-only implementer still needs an approved setup and a source for identity/session wiring.
Where should new work start?The current widget quickstart.Only with explicit Returning.AI setup approval; do not infer eligibility from this documentation.

Implementation guides