Skip to main content
Quick Summary
The useAuth hook manages user identity in the Suki Headless Web SDK. It gives your component the ability to sign users in, register new accounts, and handle security tokens automatically.

The hook returns status flags (isLoggedIn, isPending, error) and methods (login(), registerUser()) that you can use to authenticate users and manage their access to Suki services.
Last updated:December 2025

​
Overview

The useAuth hook is your primary tool for managing user identity in the Suki Headless Web SDK. In React, think of a hook as a plugin that gives your component specific abilities. In this case, useAuth gives your component the ability to sign users in, register new accounts, and handle security tokens automatically.

​
Prerequisites

Before you begin, the following guide require a partnerId and partnerToken:
  • partnerId - The unique ID you receive when you first onboard with Suki
  • partnerToken - The secure access token for the user, generated by your EHR system
If you do not have a partnerID and partnerToken, refer to the Authentication Guide guide to learn more.

​
How It Works

To use the useAuth hook, you pass it a configuration object with your partner credentials. It returns a set of data (like isLoggedIn) and methods (like login()) that you can use in your application. 
const {
  data,
  error,
  isPending,
  isLoggedIn,
  login,
  registerUser,
  updatePartnerToken,
} = useAuth({
  partnerId, // Required
  partnerToken, // Required
  providerId, // Optional
  autoRegister, // Optional
  loginOnMount, // Optional
});

​
Configuration

These are the settings you provide to set up the auth hook for Headless Web SDK in your application.
​
partnerId
string
required
The unique ID you receive when you first onboard with Suki.
​
partnerToken
string
required
The secure access token for the user, generated by your EHR system.
​
providerId
string
Optional: The unique ID of the provider in your EHR system.
​
autoRegister
boolean
Optional: If true, users will be automatically registered if they don’t have an account yet. This saves you from building a separate registration flow. Default is True.
​
loginOnMount
boolean
Optional: If true, the hook attempts to sign the user in as soon as the component loads (mounts). Default is True.
​
providerOrgId
string
The unique ID of the organization in the Suki partner system to which the provider belongs.This is required for auto-registration to work. If your autoRegister is set to true, you must provide this value.
​
providerName
string
The full name of the provider, including first name, middle name (if applicable), and last name separated by spaces.This is required for auto-registration to work. If your autoRegister is set to true, you must provide this value.
​
providerSpecialty
string
The medical specialty of the provider, which helps tailor the SDK’s functionality to specific clinical contexts.This is required for auto-registration to work. If your autoRegister is set to true, you must provide this value.
type UseAuthParams = {
  partnerId: string; // Required
  partnerToken: string; // Required
  autoRegister?: true; // This is a boolean value, Default is true
  loginOnMount?: boolean; // Optional 
  providerId?: string; // Optional
  providerName: string; // Required for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
  providerOrgId: string; // Required for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
  providerSpecialty?: string; // Required for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
} | {
  partnerId: string; // Required
  partnerToken: string; // Required
  autoRegister?: false; // Default is false
  loginOnMount?: boolean; // Optional
  providerId?: string; // Optional
}

​
What You Get

The hook returns everything you need to track the current status and take action.

​
State

Use these values to update your UI (e.g., show a spinner while loading).
​
isLoggedIn
boolean
A boolean value that indicates whether the user is currently logged in. If true, the user is logged in and can use the Suki Headless Web SDK.
​
isPending
boolean
A boolean value that indicates whether the authentication process is currently in progress (e.g., logging in or registering). If true, the hook is working and you can show a spinner to the user.
​
data.accessToken
string
The active Suki session token. This is the token that is used to authenticate the user with the Suki Headless Web SDK.
​
error
PlatformError
An error object that contains details if something goes wrong while authenticating the user. Refer to the Error Handling to check the possible error codes.

​
Actions

Call these functions to perform tasks.
​
login()
function: () => Promise<LoginResponse>
A function to start the login process for the user in your application. This function returns a promise that resolves to a LoginResponse object.

​
Login Response Example

type LoginResponse = { 
suki_token: string;
jwt_bearer: string
}
​
registerUser
function: (params: RegistrationRequest) => Promise<RegistrationResponse>
A function to start the registration process for a new user manually (using the provided partner credentials). This function returns a promise that resolves to a RegistrationResponse object.

​
Registration Response Example

type RegistrationResponse = Record<string, never>
}
Success results in an empty object. Means, the user is registered successfully and you can now sign them in using the login function.
​
updatePartnerToken
function: (partnerToken: string) => Promise<UpdatePartnerTokenResponse>
A function to update the partner token for the user. This function returns a promise that resolves to a UpdatePartnerTokenResponse object.

​
Update Partner Token Response Example

type UpdatePartnerTokenResponse = { 
suki_token: string;
jwt_bearer: string
}

​
Code Example

Security tokens often expire and refresh while a user is working. If your application refreshes its token, you must tell the Suki Headless Web SDK so the user’s voice session isn’t interrupted. You use updatePartnerToken to handle this seamlessly.
React
import { useEffect } from 'react';
import { useAuth } from '@suki-sdk/platform-react'; 

export const SukiEmbed = ({ currentPartnerToken, partnerId }) => {
  // Initialize the hook
  const { updatePartnerToken, isLoggedIn, error } = useAuth({
    partnerId, // Required
    partnerToken: currentPartnerToken, // Required, The initial token
    loginOnMount: true,                // Optional, Sign in automatically
  });

  // Listen for token changes from your parent app
  useEffect(() => {
    // If we are logged in and the parent app gives us a new token...
    if (isLoggedIn && currentPartnerToken) {
      // ...send it to Suki immediately.
      updatePartnerToken(currentPartnerToken)
        .catch((err) => console.error('Failed to update token:', err));
    }
  }, [currentPartnerToken, isLoggedIn, updatePartnerToken]);

  if (error) {
    return <div>Error signing in: {error.message}</div>;
  }

  return <div>Suki Assistant is ready</div>;
};
Using updatePartnerToken is better than unmounting and remounting the component, as it keeps the user’s connection to the Suki Headless Web SDK active and prevents dropped audio.

​
Next Steps

Refer to the Ambient Hook guide to learn more about how to use the Ambient Hook to start a voice session.