How do I get an Auth Token?

Request it from support@unifyapps.com with your environment's domain and the identity provider you use. Keep it on your server and never expose it in browser or mobile-app code.

What identifies a visitor?

The visitor username sent when creating the session. Use a stable identifier consistently; name and email are optional.

What should I do when a session expires?

Create a new session on your server and pass the new session ID to the embed. With the JavaScript SDK, call UnifyApps('update', { token: ' ' }); with the Angular SDK, call the component's update method. If session creation returns 401, check your Auth Token and the visitor details you sent.

Authentication | UnifyApps embedded integrations guide

Overview

This page explains the security and authentication model for embedding UnifyApps in your own website or product, whether you embed an application you built in UnifyApps or a platform module such as the Automation Manager.

Universal Authentication and Configuration Parameters

Parameter	Description	Scope	Data Type	How to Obtain
`HOST_NAME`	The base URL of your UnifyApps environment.	Universal	String	Your environment's domain, the address you sign in to. For example, `https://platform.unifyapps.com`.
`IDP_ID`	The identity provider that signs visitors in. The SDKs take it as `identityProviderId`.	Universal	String	For a Private app, the identity provider attached under the app's Settings > Privacy Settings > Identity providers. Ask support@unifyapps.com to set one up if you don't have one.
`AUTH_TOKEN`	A long-lived secret key your server uses to create sessions.	Server-Side	String	Request from support@unifyapps.com.
`SESSION_ID`	A one-time token for one visitor, passed to the SDK or frame. It expires about 2 minutes after it's created, unless your identity provider sets a longer time.	Client-Side	String	Created by your server. See Create a Session below.
`applicationId`	The application to embed. Also sent as the `x-ua-app` header when you create a session for an application embed.	App Embed	String	The Application ID on your application's Overview page.
`pageId`	(Optional) The page to open first. The React SDK calls it `initialPageId`.	App Embed	String	The page's Page Slug in its page settings.
`pageInputs`	(Optional) An object of input values for that page. The React SDK calls it `initialPageInputs`.	App Embed	Object	The inputs your page declares.
`containerEl`	The element on your page where the application renders. Required for the JavaScript and Angular SDKs, except for a Copilot chat application. The React SDK renders in place.	App Embed	DOM Element	A reference to an element, for example `document.getElementById('unify-container')`.

The Two-Token Security Model

UnifyApps uses a two-token model to ensure all embedded content is secure. Understanding each token's role is critical.

AUTH_TOKEN (Server-Side Secret Key)
- This is your long-lived, secret key. Use it only for server-to-server calls. If it is ever exposed, contact support@unifyapps.com to rotate it.
  Note
  Never expose your AUTH_TOKEN in any client-side code like JavaScript or a mobile app. Treat it like a password.
SESSION_ID (Client-Side Temporary Token)
- This is a one-time token for a single visitor. By default it expires about 2 minutes after it's created.
- It is safely passed to the user's browser to initialize the embedded application. The JavaScript, React and Angular SDKs take it as the token setting.

Authentication Flow

The authentication process follows a secure, server-side flow to generate the temporary SESSION_ID.

User Authenticates: A visitor signs in to your product using your existing authentication system.
Server Requests Session ID: Your server sends a POST request to the UnifyApps /auth/createUserExternalLoginSession endpoint, authenticated with your secret AUTH_TOKEN. For an application embed, it also sends the x-ua-app header set to the Application ID, which ties the session to that application.
UnifyApps Returns Session ID: UnifyApps validates the request and returns a SESSION_ID to your server.
Server Passes Session ID to Client: Your server sends the SESSION_ID to the visitor's browser.
Embed Signs In: The SDK (JavaScript, React or Angular) uses the SESSION_ID to sign the visitor in and load the embedded content. A plain iFrame opens the sign-in address built from the same session instead.

Diagram: how an embedded session is created between the browser, your server and UnifyApps

Create a Session

Every embed that signs visitors in starts with this request from your server:

// Run this on your server, never in the browser
const response = await fetch('<HOST_NAME>/auth/createUserExternalLoginSession', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <AUTH_TOKEN>',
    'Content-Type': 'application/json',
    'x-ua-app': '<APPLICATION_ID>', // for application embeds
  },
  body: JSON.stringify({
    identityProviderId: '<IDP_ID>',
    formData: {
      username: '<USER_NAME>', // a stable ID for this visitor
      name: '<NAME>', // optional
      email: '<USER_EMAIL>', // optional
    },
  }),
});
// 200: { "sessionId": "<SESSION_ID>", "redirectUrl": "<HOST_NAME>/auth/external/login?sessionId=..." }
// 401: the Auth Token is wrong or the visitor can't be signed in; the body gives the reason
const { sessionId } = await response.json();

Create a new session for every page load. A session ID works once and expires about 2 minutes after it's created, unless your identity provider is set to a longer time.
Pass sessionId to the SDK as token. Platform embeds also accept <IDP_ID>/<SESSION_ID>.
For a plain iFrame, see Application iFrame or Platform iFrame.

Public Applications

If your application is public, you don't need the server-side session call. Set isApplicationPublic: true and pass identityProviderId without a token. The SDK creates an anonymous session for the visitor.