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

# Ambient Session Workflow Overview

> Use `useAuth`, `useAmbient`, and `useAmbientSession` to authenticate users, create ambient sessions, and manage recording 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 Suki Headless Web SDK provides three primary hooks to manage your Ambient documentation workflow: `useAuth` for identity, `useAmbient` to create a session and obtain an `ambientSessionId`, and `useAmbientSession` to record, pause, resume, and submit audio for that session.
  </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">August 2026</span>
  </div>
</div>

This section provides an overview of the React <Tooltip tip="A function that allows you to use state and other React features in functional components." cta="View in Glossary" href="/Glossary/h">hooks</Tooltip> available in the Suki Headless Web SDK. Refer to the cards below for more information on each hook.

## Prerequisites to use the hooks

Before you begin, the following hooks 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.

<Note>
  If you do not have a `partnerId` and `partnerToken`, refer to the [Authentication guide](/headless-web-sdk/authentication) for more information.
</Note>

## What are the hooks?

In React, a hook adds behavior to your components. The `useAuth`, `useAmbient`, and `useAmbientSession` hooks work together in a typical workflow to enable capabilities like:

* Authenticating users
* Creating ambient sessions
* Managing recording and submitting audio

You use these hooks to in your application to manage your ambient documentation workflow.

### Workflow

Run the hooks in order. Each step depends on the output of the previous one.

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
  ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','actorBkg':'#FFF394','actorBorder':'#FFE148','actorTextColor':'#111827','actorLineColor':'#FFE148','signalColor':'#111827','signalTextColor':'#111827','labelBoxBkgColor':'#FFF394','labelBoxBorderColor':'#FFE148','labelTextColor':'#111827','loopTextColor':'#111827','activationBorderColor':'#FFE148','activationBkgColor':'#FFFADE','sequenceNumberColor':'#111827','noteBkgColor':'#FFFADE','noteBorderColor':'#FFE148','noteTextColor':'#111827'}}}%%
  sequenceDiagram
      participant App as Your component
      participant Auth as useAuth
      participant Amb as useAmbient
      participant Rec as useAmbientSession
      participant Suki as Suki platform

      Note over App,Suki: Wrap the app in PlatformClientProvider once

      Note over App,Suki: 1 · Authenticate
      App->>Auth: login() or registerUser()
      Auth->>Suki: Register / Login
      Suki-->>Auth: accessToken
      Auth-->>App: isLoggedIn

      Note over App,Suki: 2 · Create session
      App->>Amb: session.create({ encounterId })
      Amb->>Suki: Create ambient session
      Suki-->>Amb: ambientSessionId
      Amb-->>App: isSuccess · ambientSessionId

      Note over App,Suki: 3 · Record and submit
      App->>Rec: pass ambientSessionId
      App->>Rec: start()
      Rec->>Suki: Capture audio
      App->>Rec: setSessionContext()
      App->>Rec: pause() / resume()
      App->>Rec: submit()
      Rec->>Suki: Finalize recording
      Suki-->>Rec: sessionStatus completed
      Rec-->>App: sessionStatus
  ```
</div>

## Implementation guides

Choose the guide for the hook you want to implement:

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/headless-web-sdk/guides/hooks/auth-hook" arrow="true">
    Use this hook to manage authentication state for the Headless Web SDK.
  </Card>

  <Card title="Create Ambient Session" icon="plus" href="/headless-web-sdk/guides/hooks/ambient-hook" arrow="true">
    Use this hook to create a session and obtain an `ambientSessionId`.
  </Card>

  <Card title="Manage Ambient Session" icon="arrows-rotate" href="/headless-web-sdk/guides/hooks/ambient-session-hook" arrow="true">
    Use this hook to control recording and submit audio using the `ambientSessionId`.
  </Card>
</CardGroup>