Migrating To Web SDK v3

Quick summary

Breaking change: From Web SDK v3.0.0+, the Web SDK authentication is shared with the other Suki SDKs using a SukiAuthManager from @suki-sdk/core. You cannot rely on passing partnerId, partnerToken, and related fields only through initialize() or init() without constructing SukiAuthManager first.

Plan dependency upgrades and auth refactors before rolling v3 to production. Start with What changed and How to migrate, then Before and after (v2 vs v3) for code examples.

Last updated:April 2026

Overview

In v2.x.x, you managed login by passing partner credentials, provider details, and related fields within a single initialize() (JavaScript) or init() (React) call. In v3.0.0+, you must split these tasks. You still require a partner token, but you no longer provide all fields during the initialization call. Instead, you create an instance of the SukiAuthManager class from the @suki-sdk/core package. The Suki Web SDK now requires this instance to manage authentication state.

Implementation steps

Follow these steps to configure authentication:

Generate a partner token: Obtain a partner token for the current user, following the same requirement as v2.
Create a SukiAuthManager instance: Create one SukiAuthManager instance for your entire application. Pass in the token, the environment (staging or production), and the partner and provider details you previously used in v2.
Initialize the SDK: Call initialize() (JavaScript) or init() (React) and include the authManager instance along with your other Web SDK options. The Web SDK reads the authentication state directly from the authManager.

What changed

Topic	v2	v3
Where auth config lives	Partner fields passed directly into `initialize()` / `init()`	You build `new SukiAuthManager({ … })` and pass `{ authManager }` into `initialize()` or `init()`
New dependency	Not required	`@suki-sdk/core` (provides `SukiAuthManager`)
Stage vs production / test mode	Optional `isTestMode` on `initialize()` / `init()` options (Refer to InitOptions and Migration to v2) for more details	Set `environment` on `SukiAuthManager`. Do not use `isTestMode` on the Web SDK `init()` call for environment selection in v3.

In Web SDK v2, setting isTestMode to true would route the SDK to stage endpoints. In v3, isTestMode is deprecated for environment selection.

Configure staging versus production through environment on SukiAuthManager, then pass authManager into initialize() or init().
Remove isTestMode from your init options when you migrate.

How to migrate

Follow the steps below to migrate to Web SDK v3.0.0+.

Install and upgrade packages

Add @suki-sdk/core. Upgrade @suki-sdk/js or @suki-sdk/react to v3. Refer to Install packages for more details.

Create SukiAuthManager

Instantiate SukiAuthManager with your partner token, provider fields, and environment (staging/production). This replaces using isTestMode on v2 init options for stage endpoints. Create once per session after the partner token is available.

Pass authManager into the Web SDK

Replace inline auth arguments on initialize() (JavaScript) or init() (React) with a single authManager instance.

Validate in staging

Run your usual flows (login, mount, sessions) in a non-production environment before promoting to production.

Step 1: Install packages

Javascript
React

pnpm add @suki-sdk/js@latest @suki-sdk/core

pnpm add @suki-sdk/react@latest @suki-sdk/core

Step 2: Implement authentication with SukiAuthManager

Create a SukiAuthManager instance, then pass authManager into the Web SDK.

Code example: create SukiAuthManager

Javascript
React

JavaScript

import { SukiAuthManager } from "@suki-sdk/core";

const authManager = new SukiAuthManager({
  partnerId,
  partnerToken,
  environment: "production",
  autoRegister: false,
  loginOnInitialize: true,
  providerId,
  providerName,
  providerOrgId,
  providerSpecialty,
});

In React, create the manager inside a component with useMemo so you do not instantiate it on every render or at module scope. Adjust the dependency array when partnerId, partnerToken, or other constructor inputs changes.

React

import { useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";

function YourBootstrap() {
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId,
        partnerToken,
        environment: "production",
        autoRegister: false,
        loginOnInitialize: true,
        providerId,
        providerName,
        providerOrgId,
        providerSpecialty,
      }),
    [partnerId, partnerToken],
  );

  return <>{/* your app content */}</>;
}

Create the manager once per session after your identity token is available for authentication.

Step 3: Initialize the Web SDK

Initialize in JavaScript
Initialize in React

In JavaScript, create the SukiAuthManager instance once per stable set of credentials.

JavaScript

import { SukiAuthManager } from "@suki-sdk/core";
import { initialize } from "@suki-sdk/js";


const authManager = new SukiAuthManager({
  partnerId,
  partnerToken,
  environment: "production",
  autoRegister: false,
  loginOnInitialize: true,
  providerId,
  providerName,
  providerOrgId,
  providerSpecialty,
});

initialize({
  authManager, // new in v3
  enableDebug: false,
  theme,
});

The returned SDK client behavior remains aligned with v3 release notes for @suki-sdk/js.

Before and after: JavaScript `initialize` (v2 vs v3)

import { initialize } from "@suki-sdk/js";

initialize({
  partnerId,
  partnerToken,
  enableDebug: true,
  isTestMode: true,
  theme
});

In a component under SukiProvider, use the SukiAuthManager from Step 2 with useSuki(). In a useEffect, call init({ authManager, ... }) only when !isInitialized so you do not initialize twice. See the Quickstart for a full example.

React

import { useEffect, useMemo } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { useSuki } from "@suki-sdk/react"; 

function YourAppContent() {
  const authManager = useMemo(
    () =>
      new SukiAuthManager({
        partnerId,
        partnerToken,
        environment: "production",
        autoRegister: false,
        loginOnInitialize: true,
      }),
    [partnerId, partnerToken],
  );

  const { init, isInitialized } = useSuki();

  useEffect(() => {
    if (!isInitialized) {
      init({
        authManager,
        uiOptions,
        ambientOptions,
      });
    }
  }, [authManager, init, isInitialized]);

  return (
    <div>
      {/* your app content */}
    </div>
  );
}

Create the manager once per stable set of credentials (see useMemo dependencies). Apply this inside your provider tree, not at module scope.

Before and after: React `init` (v2 vs v3)

import { useEffect } from "react";
import { useSuki } from "@suki-sdk/react";

const initOptions = {
  partnerId,
  partnerToken,
  providerName,
  providerOrgId,
  isTestMode,
  enableDebug,
  theme,
};

function App() {
  const { init } = useSuki();

  useEffect(() => {
    init(initOptions);
  }, [init]);

  return (
    <div>
      {/* your app content */}
    </div>
  );
}

Migration checklist (v2 vs v3)

Upgrade @suki-sdk/js or @suki-sdk/react to v3
Add dependency @suki-sdk/core (required for SukiAuthManager)
Replace inline auth configuration with new SukiAuthManager(...)
Pass authManager into initialize() in the JavaScript SDK or init() in the React SDK
Remove isTestMode from init options; set environment on SukiAuthManager instead of using isTestMode for stage versus production behavior

Next steps

InitOptions

Learn about the options you can pass on init option types

AuthConfig (SukiAuthManager)

All fields you can pass into SukiAuthManager

Migration To v2

Start here if you are still on Web SDK v1.x.x

Web SDK Quickstart

Handle Web SDK errors after you migrate

Get Started

Web SDK Guides

API Reference

Examples

FAQs

Migrating To Web SDK v3

Overview

Implementation steps

What changed

How to migrate

Step 1: Install packages

Step 2: Implement authentication with SukiAuthManager

Code example: create SukiAuthManager

Step 3: Initialize the Web SDK

Before and after: JavaScript `initialize` (v2 vs v3)

Before and after: React `init` (v2 vs v3)

Migration checklist (v2 vs v3)

Next steps

InitOptions

AuthConfig (SukiAuthManager)

Migration To v2

Web SDK Quickstart

Get Started

Web SDK Guides

API Reference

Examples

FAQs

​Overview

​Implementation steps

​What changed

​How to migrate

​Step 1: Install packages

​Step 2: Implement authentication with SukiAuthManager

​Code example: create SukiAuthManager

​Step 3: Initialize the Web SDK

​Before and after: JavaScript initialize (v2 vs v3)

​Before and after: React init (v2 vs v3)

​Migration checklist (v2 vs v3)

​Next steps

InitOptions

AuthConfig (SukiAuthManager)

Migration To v2

Web SDK Quickstart

Overview

Implementation steps

What changed

How to migrate

Step 1: Install packages

Step 2: Implement authentication with SukiAuthManager

Code example: create SukiAuthManager

Step 3: Initialize the Web SDK

Before and after: JavaScript `initialize` (v2 vs v3)

Before and after: React `init` (v2 vs v3)

Migration checklist (v2 vs v3)

Next steps