> ## Documentation Index
> Fetch the complete documentation index at: https://vida.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed the Vida app

> Authenticate a reseller customer from your backend and open the Vida application in an iframe.

Eligible resellers can embed the Vida application inside their own product. Your backend identifies
the customer and user, requests a one-time Vida authentication token, and returns that short-lived
token to your frontend. Your frontend opens `/app/embed` on your Vida domain.

<Warning>
  Never put a long-lived Vida API token in frontend code, an iframe URL, or browser storage. Generate
  one-time user authentication tokens only from an authenticated backend you control.
</Warning>

## Before you begin

You need:

* an eligible Vida reseller account;
* a Vida domain, such as `agents.example.com`;
* a trusted mapping between each customer in your system and its Vida organization;
* a backend that can authenticate the current user and call the Vida API.

If your account does not manage downstream organizations, use the normal Vida application rather
than creating an unnecessary reseller hierarchy.

## 1. Resolve the customer organization

Store the Vida organization ID when you create a customer. Also send your own stable
`externalAccountId` so the organization can be reconciled later.

* Create a customer organization with the documented Organizations API.
* Resolve an existing customer through `GET /api/v2/getAccountByExternalId` when you have its
  external ID.

Confirm the returned organization belongs to the authenticated reseller before issuing user access.

## 2. Generate a one-time authentication token

From your backend, call:

```text theme={null}
GET /api/v2/auth/account/oneTimeAuthToken
```

Supply the user's email and, when needed, the customer organization's `externalAccountId`. If the
email is not already a member and the external organization is valid, Vida can create the member
without sending an invitation email.

The response includes `authToken` and the authenticated account ID. Return the one-time token to
your frontend only after verifying the current user belongs to that customer in your system.

## 3. Build the iframe URL

Use `/app/embed` on your Vida or white-label domain:

```js theme={null}
const url = new URL("https://agents.example.com/app/embed");
url.searchParams.set("authToken", oneTimeAuthToken);
url.searchParams.set("email", currentUser.email);
```

The email must match the Vida account authenticated by the token. Use `URL` and `searchParams`
instead of concatenating unescaped query strings.

Render the result:

```html theme={null}
<iframe
  src="https://agents.example.com/app/embed?authToken=ONE_TIME_TOKEN&email=user%40example.com"
  title="Vida"
  allow="camera; microphone"
  style="width: 100%; height: 100vh; border: 0"
></iframe>
```

An end-to-end example is available in the
[Vida app embed demo](https://github.com/VIDA-Global/vida-app-embed-demo).

## Optional destination and onboarding values

`redirectUrl` can select a destination inside the same embedded Vida application. Supply a
URL-encoded `/app/...` destination; external origins and another `/app/embed` loader are rejected.

For new organizations, you may preselect a template and prefill onboarding:

| Query value                                | Purpose                                                               |
| ------------------------------------------ | --------------------------------------------------------------------- |
| `templateId`                               | Select an available reseller Agent template.                          |
| `onboarding_timezone`                      | Prefill an IANA timezone such as `America/Chicago`.                   |
| `onboarding_agentVoice`                    | Prefill an available Agent voice ID.                                  |
| `onboarding_tf_<fieldKey>`                 | Prefill one template field. Repeat the parameter for multiple values. |
| `onboarding_skip_tf_<fieldKey>=true`       | Skip one template field.                                              |
| `onboarding_skip_ti_<integrationKey>=true` | Skip one template integration.                                        |
| `onboarding_skipTimezone=true`             | Skip the timezone step.                                               |
| `onboarding_skipAgentVoice=true`           | Skip the voice step.                                                  |

Prefilling a value does not automatically skip its step. Unknown or unavailable values may be
ignored. Treat onboarding query values as draft inputs, then read and verify the resulting
organization and Agent configuration.

## Production checklist

* Verify the signed-in user-to-customer mapping on every token request.
* Keep the Vida API token server-side.
* Use HTTPS for your product and Vida domain.
* Confirm the iframe host's Content Security Policy permits the Vida domain.
* Test login, logout, account switching, microphone permission, onboarding, and deep links.
* Do not reuse or cache one-time authentication tokens.

For API-managed domains and the full backend sequence, see
[White-label domains and embedded access](/docs/api-reference/platform-guides/white-label-domains-and-embed).