# 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.

> Signed does not mean hidden
>
> The browser can read the signed token's claims, including user identifiers. Signing prevents undetected changes; it does not hide those claims. Keep access credentials on the server, include only the configured identifiers, and never log tokens.

### 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](https://docs.returning.ai/embed-script/auth-attribute.md).

If you only need a public campaign, a configured [open banner](https://docs.returning.ai/widget-sdk/banner.md) may fit. It does not provide the same experience as a personalized rewards widget. Use the [integration chooser](https://docs.returning.ai/choose.md) 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](https://docs.returning.ai/broker-integrations/users.md#membership-check). 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](https://docs.returning.ai/widget-sdk/auth-access-key.md#step-2-backend-endpoint) and [framework-independent quickstart](https://docs.returning.ai/widget-sdk.md). 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](https://docs.returning.ai/widget-sdk/auth-access-key.md#token-lifecycle). 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](https://docs.returning.ai/broker-integrations/launch-checklist.md#decision-gates).

## Comparison

| Question | Access Key Embed | Legacy 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

- [Access Key authentication](https://docs.returning.ai/widget-sdk/auth-access-key.md): complete server examples and current lifecycle.
- [Legacy attribute authentication](https://docs.returning.ai/embed-script/auth-attribute.md): supplied-setup approval required.
- [Migration to Access Key Embed](https://docs.returning.ai/widget-sdk/auth-token.md#migrating-to-access-key): inventory and cutover checks for an older installation.
- [Legacy server proxy](https://docs.returning.ai/server-proxy.md): retain only as agreed for your setup.