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

# Web SDK Authentication

> Authenticate the Suki Web SDK with SukiAuthManager in JavaScript or React

The Suki Web SDK uses the `SukiAuthManager` class from `@suki-sdk/core` to authenticate users. Create one auth manager after your application receives the user's Partner Token, then pass it to `initialize()` in JavaScript or `init()` in React.

<Note>
  Web SDK v3 changes how you configure authentication. If you are upgrading from Web SDK v2, follow the [Web SDK v3 migration guide](/web-sdk/product-updates/migration-to-v3) to update your integration.
</Note>

## Prerequisites

Before you configure authentication, ensure that:

* You have completed [Partner onboarding](/documentation/get-started/partner-onboarding) and received your Partner ID.
* Your identity provider issues a signed Partner Token (JWT) after the user signs in.
* Suki has your public keys or JWKS endpoint and knows which JWT claim identifies the user.
* You have installed `@suki-sdk/core` with either `@suki-sdk/js` or `@suki-sdk/react`.

For Partner Token and JWKS requirements, refer to [Partner authentication](/documentation/how-to/partner-authentication).

## How Web SDK authentication works

<Steps>
  <Step title="User Sign-In">
    The user signs in through your application. Your identity provider issues a **Partner Token** for that user.
  </Step>

  <Step title="Create SukiAuthManager">
    Your application creates `SukiAuthManager` with the Partner ID, Partner Token, environment, and provider details.
  </Step>

  <Step title="Initialize the Web SDK">
    The Web SDK uses the `SukiAuthManager` instance to authenticate the user during initialization and exchanges the Partner Token for access to Suki services.
  </Step>
</Steps>

<Note>
  Create one `SukiAuthManager` instance for each stable set of user credentials. Do not create a new instance on every React render.
</Note>

## Configure SukiAuthManager

Pass your authentication and provider values to `SukiAuthManager`:

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

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", 
  partnerToken: "YOUR_PARTNER_TOKEN", 
  environment: "production",
  autoRegister: true,
  loginOnInitialize: true,
  providerId: "YOUR_PROVIDER_ID",
  providerName: "YOUR_PROVIDER_NAME",
  providerOrgId: "YOUR_PROVIDER_ORG_ID",
  providerSpecialty: "FAMILY_MEDICINE",
});
```

<Note>
  The examples set `loginOnInitialize: true` so `SukiAuthManager` authenticates when you create the instance. If you use the default value of `false`, call `await authManager.login()` after creating the instance and before passing it to `initialize()` or `init()`.
</Note>

<Expandable title="SukiAuthManager Configuration Fields" defaultOpen={true}>
  <ResponseField name="partnerId" type="string" required>
    Partner ID provided by Suki during onboarding
  </ResponseField>

  <ResponseField name="partnerToken" type="string" required>
    Signed JWT issued by your identity provider for the current user
  </ResponseField>

  <ResponseField name="environment" type={'"production" | "staging"'}>
    **Optional** Suki environment used by the SDK; the default is **`"production"`**
  </ResponseField>

  <ResponseField name="autoRegister" type="boolean" default="true">
    **Optional** When **`true`**, the SDK registers the provider automatically if the provider does not already exist in the Suki Platform; **`providerName`** and **`providerOrgId`** are required; when **`false`**, automatic registration is disabled, and the provider must already exist
  </ResponseField>

  <ResponseField name="loginOnInitialize" type="boolean" default="false">
    **Optional** When **`true`**, **`SukiAuthManager`** authenticates during initialization; when **`false`**, call **`login()`** before using authenticated SDK operations
  </ResponseField>

  <ResponseField name="providerId" type="string">
    **Optional** Provider identifier from your system
  </ResponseField>

  <ResponseField name="providerName" type="string">
    **Optional** Full provider name; this field is required for registration and auto-registration
  </ResponseField>

  <ResponseField name="providerOrgId" type="string">
    **Optional** Organization identifier for the provider; this field is required for registration and auto-registration
  </ResponseField>

  <ResponseField name="providerSpecialty" type="string">
    **Optional** Provider specialty, such as **`FAMILY_MEDICINE`**
  </ResponseField>
</Expandable>

<Warning>
  In Web SDK v3, set the target environment in `SukiAuthManager`. Use `"staging"` while testing and `"production"` when you go live. Do not use `isTestMode` in `initialize()` or `init()`.
</Warning>

## Authenticate with JavaScript

Create the auth manager after the Partner Token is available, then pass it to `initialize()`:

```javascript JavaScript 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: "YOUR_PARTNER_ID",
  partnerToken: "YOUR_PARTNER_TOKEN",
  environment: "production",
  autoRegister: true,
  loginOnInitialize: true,
  providerId: "YOUR_PROVIDER_ID",
  providerName: "YOUR_PROVIDER_NAME",
  providerOrgId: "YOUR_PROVIDER_ORG_ID",
  providerSpecialty: "FAMILY_MEDICINE",
});

const sdkClient = initialize({
  authManager,
});
```

Reuse `sdkClient` for Web SDK operations. Do not call `initialize()` again for the same user session.

## Authenticate with React

Wrap your application with `SukiProvider`. In a child component, create the auth manager with `useMemo()`, then pass it to `init()` from `useSuki()`.

<CodeGroup>
  ```tsx App.tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiProvider } from "@suki-sdk/react";
  import { SukiAuthentication } from "./SukiAuthentication";

  export function App() {
    return (
      <SukiProvider>
        <SukiAuthentication />
      </SukiProvider>
    );
  }
  ```

  ```tsx SukiAuthentication.tsx 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";

  export function SukiAuthentication() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "YOUR_PARTNER_ID",
          partnerToken: "YOUR_PARTNER_TOKEN",
          environment: "production",
          autoRegister: true,
          loginOnInitialize: true,
          providerId: "YOUR_PROVIDER_ID",
          providerName: "YOUR_PROVIDER_NAME",
          providerOrgId: "YOUR_PROVIDER_ORG_ID",
          providerSpecialty: "FAMILY_MEDICINE",
        }),
      [],
    );

    const { init, isInitialized } = useSuki();

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

    return null;
  }
  ```
</CodeGroup>

Keep the auth manager inside the `SukiProvider` component tree. Memoize it so React re-renders do not create duplicate instances.

## Update an expiring Partner Token

The Web SDK refreshes its Suki access token while the current Partner Token remains valid. When your identity provider rotates the Partner Token, update the existing SDK session instead of creating another auth manager.

<CodeGroup>
  ```javascript JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdkClient.setPartnerToken(newPartnerToken);
  ```

  ```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useEffect } from "react";
  import { useSuki } from "@suki-sdk/react";

  function PartnerTokenSync({ partnerToken }) {
    const { setPartnerToken } = useSuki();

    useEffect(() => {
      setPartnerToken(partnerToken);
    }, [partnerToken, setPartnerToken]);

    return null;
  }
  ```
</CodeGroup>

For token lifecycle details, refer to [Token refresh](/web-sdk/guides/token-refresh).

## Next steps

<Icon icon="file-lines" iconType="solid" /> Follow the [Web SDK quickstart](/web-sdk/quickstart) to mount the SDK UI after authentication.

<Icon icon="file-lines" iconType="solid" /> Review [Migrating to Web SDK v3](/web-sdk/product-updates/migration-to-v3) if your integration still passes partner fields directly to `initialize()` or `init()`.