Web SDK Authentication

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.

Web SDK v3 changes how you configure authentication. If you are upgrading from Web SDK v2, follow the Web SDK v3 migration guide to update your integration.

Prerequisites

Before you configure authentication, ensure that:

You have completed 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.

How Web SDK authentication works

User Sign-In

The user signs in through your application. Your identity provider issues a Partner Token for that user.

Create SukiAuthManager

Your application creates SukiAuthManager with the Partner ID, Partner Token, environment, and provider details.

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.

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

Configure SukiAuthManager

Pass your authentication and provider values to SukiAuthManager:

JavaScript

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",
});

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().

Hide SukiAuthManager Configuration Fields

string

required

Partner ID provided by Suki during onboarding

string

required

Signed JWT issued by your identity provider for the current user

"production" | "staging"

Optional Suki environment used by the SDK; the default is "production"

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

Optional When true, SukiAuthManager authenticates during initialization; when false, call login() before using authenticated SDK operations

string

Optional Provider identifier from your system

string

Optional Full provider name; this field is required for registration and auto-registration

string

Optional Organization identifier for the provider; this field is required for registration and auto-registration

string

Optional Provider specialty, such as FAMILY_MEDICINE

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().

Authenticate with JavaScript

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

JavaScript

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().

import { SukiProvider } from "@suki-sdk/react";
import { SukiAuthentication } from "./SukiAuthentication";

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

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;
}

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.

sdkClient.setPartnerToken(newPartnerToken);

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

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

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

  return null;
}

For token lifecycle details, refer to Token refresh.

Next steps

Follow the Web SDK quickstart to mount the SDK UI after authentication. Review Migrating to Web SDK v3 if your integration still passes partner fields directly to initialize() or init().

Get Started

Concepts & Feature Guides

API Reference

Resources

Web SDK Authentication

Prerequisites

How Web SDK authentication works

Configure SukiAuthManager

Authenticate with JavaScript

Authenticate with React

Update an expiring Partner Token

Next steps

​Prerequisites

​How Web SDK authentication works

​Configure SukiAuthManager

​Authenticate with JavaScript

​Authenticate with React

​Update an expiring Partner Token

​Next steps

Prerequisites

How Web SDK authentication works

Configure SukiAuthManager

Authenticate with JavaScript

Authenticate with React

Update an expiring Partner Token

Next steps