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

# Authentication Hook

> Learn how to use the useAuth hook to manage user identity, tokens, and login state in the Headless Web SDK

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

    <br />

    <br />

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

The **`useAuth`** hook allows you to manage user identity in the Suki Headless Web SDK. It exposes sign-in and registration methods, token updates, and status flags so your UI can react to authentication without wiring a low-level client through props.

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.

## Configuration

The **`useAuth`** hook must run under **`PlatformClientProvider`** (with a shared **`PlatformClient`** at the app root). Refer to [Platform client and provider](/headless-web-sdk/api-reference/platform-client) for more information.

You also need a **`partnerId`** and **`partnerToken`**:

* **`partnerId`:** The unique ID you receive when you onboard with Suki.
* **`partnerToken`:** The secure access token for the user, generated by your EHR system.

<Note>
  If you do not have a **`partnerId`** and **`partnerToken`**, refer to the [Partner onboarding](/documentation/partner-onboarding) guide to learn how to get them.
</Note>

### Common use cases

<Steps>
  <Step title="Authenticate users" icon="user">
    Use **`login()`** when your application manages sign-in explicitly. Alternatively, enable **`loginOnMount`** to automatically attempt sign-in when the component mounts.

    Use the returned authentication state values to manage UI and downstream workflows:

    * **`isLoggedIn`** to determine whether the user is authenticated
    * **`isPending`** to display loading or disabled states during sign-in
    * **`data.accessToken`** to access the authenticated session token for subsequent API calls or hooks
  </Step>

  <Step title="Register new users" icon="user-plus">
    Use **`registerUser()`** to implement an explicit user registration flow.

    To automatically register users who do not already have an account, enable **`autoRegister`**. When **`autoRegister`** is set to `true`, you must also provide the following configuration values:

    * **`providerOrgId`**
    * **`providerName`**
    * **`providerSpecialty`**

    For configuration details, refer to [Configuration](#use-auth-hook-configuration) below.
  </Step>

  <Step title="Refresh partner authentication tokens" icon="arrows-rotate">
    Call **`updatePartnerToken()`** whenever your host application issues a new **`partnerToken`**.

    Refreshing the token ensures that active sessions remain authenticated and prevents session expiration during long-running workflows. For an implementation example, refer to [Code example](#code-example) below.
  </Step>

  <Step title="Handle authentication and registration errors" icon="exclamation-triangle">
    Use **`error`** to inspect authentication and registration failures and implement retry or user-facing error handling logic.

    For supported error codes and handling guidance, refer to [Error handling](/headless-web-sdk/guides/error-handling).
  </Step>
</Steps>

<Note>
  **Important:**

  When **`autoRegister`** is `true`, **`providerOrgId`**, **`providerName`**, and **`providerSpecialty`** are required on the hook params so auto-registration can succeed.
</Note>

## useAuth hook

### Usage

Pass a configuration object with **`partnerId`**, **`partnerToken`**, and optional fields (`providerId`, **`autoRegister`**, **`loginOnMount`**, and provider metadata when auto-registration is on).

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const {
  data,
  error,
  isPending,
  isLoggedIn,
  login,
  registerUser,
  updatePartnerToken,
} = useAuth({
  partnerId, // Required
  partnerToken, // Required
  providerId, // Optional
  autoRegister, // Optional
  loginOnMount, // Optional
}); 
```

### Returns

The hook returns status fields and actions whose shapes are documented under [What you get](#what-you-get) (`isLoggedIn`, `isPending`, `data`, `error`, and `login()`, `registerUser()`, `updatePartnerToken()`).

### How the hook works

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
flowchart TD
    A[Configure useAuth hook] --> B{Mounted?}
    B -->|yes| C[Call login automatically]
    B -->|no| D[Manual login]
    C --> E{Authentication status}
    D --> E
    E --> J[User authenticated]
    J --> L[Use Suki Headless Web SDK]
    
    style A fill:#FFF394,stroke:#D4A017,color:#000000
    style J fill:#FFF394,stroke:#D4A017,color:#000000
    style L fill:#FFF394,stroke:#D4A017,color:#000000
```

### Configuration

<span id="use-auth-hook-configuration" />

These are the settings you provide to set up the **auth** hook for Headless Web SDK in your application.

<ResponseField name="partnerId" type="string" required>
  The unique ID you receive when you first onboard with Suki.
</ResponseField>

<ResponseField name="partnerToken" type="string" required>
  The secure access token for the user, generated by your EHR system.
</ResponseField>

<ResponseField name="providerId" type="string">
  **Optional**: The unique ID of the provider in your EHR system.
</ResponseField>

<ResponseField name="autoRegister" type="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`.
</ResponseField>

<ResponseField name="loginOnMount" type="boolean">
  **Optional**: If true, the hook attempts to sign the user in as soon as the component loads (mounts). Default is `True`.
</ResponseField>

<ResponseField name="providerOrgId" type="string">
  The unique ID of the organization in the Suki partner system to which the provider belongs.

  This is <Badge color="red" size="sm">required</Badge> for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
</ResponseField>

<ResponseField name="providerName" type="string">
  The full name of the provider, including first name, middle name (if applicable), and last name separated by spaces.

  This is <Badge color="red" size="sm">required</Badge> for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
</ResponseField>

<ResponseField name="providerSpecialty" type="string">
  The medical specialty of the provider, which helps tailor the SDK's functionality to specific clinical contexts.

  This is <Badge color="red" size="sm">required</Badge> for auto-registration to work. If your `autoRegister` is set to `true`, you must provide this value.
</ResponseField>

```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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).

<ResponseField name="isLoggedIn" type="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.
</ResponseField>

<ResponseField name="isPending" type="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.
</ResponseField>

<ResponseField name="data.accessToken" type="string">
  The active Suki session token. This is the token that is used to authenticate the user with the Suki Headless Web SDK.
</ResponseField>

<ResponseField name="error" type="PlatformError">
  An error object that contains details if something goes wrong while authenticating the user. Refer to the
  [Error handling](/headless-web-sdk/guides/error-handling) to check the possible error codes.
</ResponseField>

### Actions

Call these functions to perform tasks.

<ResponseField name="login()" type=" 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

  ```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  type LoginResponse = { 
  suki_token: string;
  jwt_bearer: string
  }
  ```
</ResponseField>

<ResponseField name="registerUser" type=" 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

  ```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  type RegistrationResponse = Record<string, never>
  ```

  <Note>
    Success results in an empty object. This means the user is registered successfully and you can now sign them in using the `login` function.
  </Note>
</ResponseField>

<ResponseField name="updatePartnerToken" type=" function: (partnerToken: string) => Promise<UpdatePartnerTokenResponse>">
  A **function** to update the `partnerToken` for the user. This function returns a promise that resolves to a `UpdatePartnerTokenResponse` object.

  #### Update Partner Token Response Example

  ```tsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  type UpdatePartnerTokenResponse = { 
  suki_token: string;
  jwt_bearer: string
  }
  ```
</ResponseField>

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

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

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

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Ambient hook](/headless-web-sdk/guides/hooks/ambient-hook) guide to learn more about how to use it to start a voice session.