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

# Migrating To Web SDK v3

> Learn how to migrate from Web SDK v2 to v3

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

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

    <br />

    <br />

    <Danger>
      Plan dependency upgrades and auth refactors before rolling v3 to production. Start with [What changed](#what-changed) and [How to migrate](#how-to-migrate), then [Before and after (v2 vs v3)](#before-and-after-v2-vs-v3) for code examples.
    </Danger>
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

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 **`partnerToken`**, 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:

1. **Generate a `partnerToken`**: Obtain a `partnerToken` for the current user, following the same requirement as v2.

2. **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.

3. **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 <code>initialize()</code> / <code>init()</code>                                                                                                                                                              | You build <code>new SukiAuthManager(\{ ... })</code> and pass <code>\{ authManager }</code> into <code>initialize()</code> or <code>init()</code>              |
| New dependency                  | Not required                                                                                                                                                                                                                                     | <code>@suki-sdk/core</code> (provides <code>SukiAuthManager</code>)                                                                                            |
| Stage vs production / test mode | Optional <code>isTestMode</code> on <code>initialize()</code> / <code>init()</code> options (Refer to [InitOptions](/web-sdk/api-reference/types/init-options) and [Migration to v2](/web-sdk/product-updates/migration-to-v2)) for more details | Set <code>environment</code> on <code>SukiAuthManager</code>. Do not use <code>isTestMode</code> on the Web SDK `init()` call for environment selection in v3. |

<Note>
  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.
</Note>

## How to migrate

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

<Steps>
  <Step title="Install and upgrade packages" icon="download">
    Add **`@suki-sdk/core`**. Upgrade **`@suki-sdk/js`** or **`@suki-sdk/react`** to v3. Refer to [Install packages](#step-1-install-packages) for more details.
  </Step>

  <Step title="Create SukiAuthManager" icon="key">
    Instantiate **`SukiAuthManager`** with your `partnerToken`, provider fields, and **`environment`** (staging/production). This replaces using **`isTestMode`** on v2 init options for stage endpoints. Create **once per session** after the `partnerToken` is available.
  </Step>

  <Step title="Pass authManager into the Web SDK" icon="plug">
    Replace inline auth arguments on <code>initialize()</code> (JavaScript) or <code>init()</code> (React) with a single <code>authManager</code> instance.
  </Step>

  <Step title="Validate in staging" icon="check">
    Run your usual flows (login, mount, sessions) in a non-production environment before promoting to production.
  </Step>
</Steps>

## Step 1: Install packages

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/js@latest @suki-sdk/core
    ```

    ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/js@latest @suki-sdk/core
    ```

    ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/js@latest @suki-sdk/core
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/react@latest @suki-sdk/core
    ```

    ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/react@latest @suki-sdk/core
    ```

    ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/react@latest @suki-sdk/core
    ```
  </CodeGroup>
</View>

## Step 2: Implement authentication with SukiAuthManager

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

<span id="before-and-after-v2-vs-v3" />

### Code example: create SukiAuthManager

<View title="JavaScript" icon="js">
  ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";

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

<View title="React" icon="react">
  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 change.

  ```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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 */}</>;
  }
  ```
</View>

<Note>
  Create the manager **once per session** after your identity token is available for authentication.
</Note>

## Step 3: Initialize the Web SDK

<View title="JavaScript" icon="js">
  In JavaScript, create the `SukiAuthManager` instance once per stable set of credentials.

  ```javascript JavaScript highlight={2,12-17} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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,
  });
  ```

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

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

  <CodeGroup>
    ```javascript JavaScript - SDK (v2)  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { initialize } from "@suki-sdk/js";

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

    ```javascript JavaScript - SDK (v3)  theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiAuthManager } from "@suki-sdk/core";
    import { initialize } from "@suki-sdk/js";

    const authManager = new SukiAuthManager({
      partnerId,
      partnerToken,
      environment: "staging",
    });

    initialize({
      authManager,
      enableDebug: true,
      theme
    });
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  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](/web-sdk/quickstart) for a full example.

  ```tsx React highlight={1,3,17-28} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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)

  <CodeGroup>
    ```tsx React - SDK (v2) theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    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>
      );
    }
    ```

    ```tsx React - SDK (v3) theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect, useMemo } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { useSuki } from "@suki-sdk/react";

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

      const { init, isInitialized } = useSuki();

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

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

## 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

<CardGroup cols={2}>
  <Card title="InitOptions" icon="gear" arrow={true} href="/web-sdk/api-reference/types/init-options">
    Learn about the options you can pass on init option types
  </Card>

  <Card title="AuthConfig (SukiAuthManager)" icon="key" arrow={true} href="/dictation-sdk/guides/configuration#authconfig">
    All fields you can pass into SukiAuthManager
  </Card>

  <Card title="Migration To v2" icon="memo" arrow={true} href="/web-sdk/product-updates/migration-to-v2">
    Start here if you are still on Web SDK v1.x.x
  </Card>

  <Card title="Web SDK Quickstart" icon="rocket" arrow={true} href="/web-sdk/quickstart">
    Handle Web SDK errors after you migrate
  </Card>
</CardGroup>