This guide covers the full lifecycle of the Agent SDK - OAuth sign-in (with optional SSO), initialization, lifecycle events, and a clean teardown.
Personas: Developer / Integrator - the host application initializes, restores, and tears down the session the same way for every signed-in user.
The SDK authenticates agents via OAuth through the Avaya Infinity™ login, which can be federated to a corporate IdP for SSO. You choose the OAuth flow mode during initialization:
| Mode | Behavior | Best for |
|---|---|---|
redirect (default) |
Navigates the page to the IdP login | Standalone SPAs |
popup |
Opens the IdP login in a popup window | Embedded environments (Salesforce iframes etc.) |
Collect these from your Avaya Infinity™ account administrator:
avayaInfinityHost - e.g. api.avayacloud.com.clientId - generated when an Agent SDK integration is provisioned.oAuthRedirectUri - must match a redirect URI registered on the integration. In popup mode this URI also hosts the callback page.idpHint (optional) - identity provider alias for one-click SSO.These are provided through AvayaInfinityAgentSdkInitParams as an argument to AvayaInfinityAgentSdk.init.
AvayaInfinityAgentSdk.init is the single entry point. It performs the Agent Authentication and returns a promise which resolves to a User representing the authenticated agent.
import { AvayaInfinityAgentSdk } from "@avaya/infinity-agent-sdk";
const user = await AvayaInfinityAgentSdk.init({
avayaInfinityHost: "api.avayacloud.com",
clientId: "your-client-id",
oAuthRedirectUri: window.location.origin,
});
Redirect mode (default): init() navigates the page to the IdP. After login, the IdP redirects back with an authorization code and your app must call init() again to resume the initialization. The first call returns a never-resolving promise - make sure your app calls init() on every page load.
Popup mode: init() opens the IdP in a popup; the current page stays put and the promise resolves once authentication completes. Create a callback page and provide it's link as oAuthRedirectUri.
loginButton.addEventListener("click", async () => {
const user = await AvayaInfinityAgentSdk.init({
avayaInfinityHost: "api.avayacloud.com",
clientId: "your-client-id",
oAuthRedirectUri: "https://your-app.com/callback",
oAuthMode: "popup",
});
});
Popup mode needs a page at oAuthRedirectUri that forwards the authorization code back to the opener window. Call AvayaInfinityAgentSdk.handleOAuthCallback from that page; the helper extracts the code, posts it back, and closes the popup:
// callback.ts (hosted at oAuthRedirectUri)
import { AvayaInfinityAgentSdk } from "@avaya/infinity-agent-sdk";
AvayaInfinityAgentSdk.handleOAuthCallback();
If your tenant is federated to a corporate IdP, pass idpHint to skip the IdP-selection screen and route the agent straight to their provider:
const user = await AvayaInfinityAgentSdk.init({
avayaInfinityHost: "api.avayacloud.com",
clientId: "your-client-id",
oAuthRedirectUri: window.location.origin,
idpHint: "entra-id", // IdP alias
});
Subscribe via AvayaInfinityAgentSdk.subscribe:
| Event | When it fires |
|---|---|
| SdkEventType.SDK_INITIALIZED | init() completed |
| SdkEventType.INITIALIZATION_FAILED | init() failed |
| SdkEventType.TOKEN_REFRESH_FAILED | OAuth token refresh failed; the SDK self-destructs |
| SdkEventType.SESSION_DESTROYED | Server invalidated the session; the SDK self-destructs |
| SdkEventType.SDK_DESTROYED | destroy() completed |
Both SdkEventType.TOKEN_REFRESH_FAILED and SdkEventType.SESSION_DESTROYED signal that the session ended without your app calling AvayaInfinityAgentSdk.destroy - the SDK tears itself down in response. Subscribe to both and route the agent back to a signed-out / re-login state:
// Session ended unexpectedly - OAuth token refresh was exhausted.
AvayaInfinityAgentSdk.subscribe(SdkEventType.TOKEN_REFRESH_FAILED, () => {
showReloginModal();
});
// Session was invalidated server-side (e.g. revoked or forced logout).
AvayaInfinityAgentSdk.subscribe(SdkEventType.SESSION_DESTROYED, () => {
showReloginModal();
});
When the SDK is no longer needed or the agent wants to log out, call AvayaInfinityAgentSdk.destroy. Calling destroy() will teardown the SDK:
await AvayaInfinityAgentSdk.destroy();
All failures surface as typed AvayaInfinityAgentSdkErrors. Errors on the SDK lifecycle path belong to the ASE_1xxx family - match error.code against AvayaInfinityAgentSdkErrorCodes to identify the specific failure. If no specific code applies, the SDK falls back to ASE_1000.
If token-refresh fails mid-session (after retries are exhausted), the SDK surfaces SdkEventType.TOKEN_REFRESH_FAILED and begins teardown automatically. Once complete, SdkEventType.SDK_DESTROYED is raised.