Skip to main content
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.
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.

​
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:
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:
The email must match the Vida account authenticated by the token. Use URL and searchParams instead of concatenating unescaped query strings. Render the result:
An end-to-end example is available in the 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: 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.