> ## 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 and Session Flow

> Build a React component that signs in, creates an ambient session with encounterId, and controls recording with sessionStatus and local phase state

This example shows how to sign in, create an ambient session, and record in one component. First sign in. Then create a session with an **`encounterId`**. Then start recording.

Use **`sessionStatus`** for the session lifecycle, such as `created` or `submitted`.

<Warning>
  Do not use **`sessionStatus`** for recording versus paused. Keep a local **`phase`** value for your start, pause, and resume buttons.
</Warning>

## Code example

```tsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import { useState, useEffect } from 'react';
import { useAuth, useAmbient, useAmbientSession } from '@suki-sdk/platform-react';

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);
  // sessionStatus does not include "recording" or "paused". Track those locally.
  const [phase, setPhase] = useState('idle'); // 'idle' | 'recording' | 'paused'

  // Step 1: Authenticate
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id',// Required
    partnerToken: 'your-partner-token',// Required
    autoRegister: true, // Required for auto-registration
    loginOnMount: true, // Optional
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'FAMILY_MEDICINE' // Required for auto-registration
  });

  // Step 2: Create session (encounterId is required)
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

  useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create({ encounterId: 'your-encounter-id' });
    }
  }, [isLoggedIn, sessionCreated, create]);

  useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

  // Step 3: Manage recording
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType,
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId
  });

  async function handleStart() {
    await start();
    setPhase('recording');
    await setSessionContext({
      patient: { dob: '1980-01-15', sex: 'M' },
      provider: { specialty: 'FAMILY_MEDICINE', role: 'Attending Physician' },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Medication review'
      }
    });
  }

  async function handlePause() {
    await pause();
    setPhase('paused');
  }

  async function handleResume() {
    await resume();
    setPhase('recording');
  }

  if (authPending) {
    return <div>Authenticating...</div>;
  }

  if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

  if (!sessionId) {
    return <div>Creating session...</div>;
  }

  return (
    <div>
      <h2>Session status: {sessionStatus}</h2>
      {sessionType === 'offline' && (
        <p>Session will sync when online</p>
      )}

      {sessionStatus === 'created' && phase === 'idle' && (
        <button type="button" onClick={handleStart}>Start Recording</button>
      )}

      {sessionStatus === 'created' && phase === 'recording' && (
        <>
          <button type="button" onClick={handlePause}>Pause</button>
          <button type="button" onClick={submit}>Submit</button>
        </>
      )}

      {sessionStatus === 'created' && phase === 'paused' && (
        <>
          <button type="button" onClick={handleResume}>Resume</button>
          <button type="button" onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}
```

### Key implementation details

<AccordionGroup>
  <Accordion title="Step 1: Authentication">
    Use **`useAuth`** to sign in. With **`autoRegister: true`** and **`loginOnMount: true`**, sign-in runs on mount. Pass **`providerName`**, **`providerOrgId`**, and **`providerSpecialty`** when auto-registration is on. Prefer specialty enum tokens such as **`FAMILY_MEDICINE`**. See [Authentication hook](/headless-web-sdk/guides/hooks/auth-hook).
  </Accordion>

  <Accordion title="Step 2: Session Creation">
    Call **`session.create({ encounterId })`** only after the user is signed in. **`encounterId`** is required. Wait for **`isSuccess`** before you use **`ambientSessionId`**. See [Create ambient session](/headless-web-sdk/guides/hooks/ambient-hook).
  </Accordion>

  <Accordion title="Step 3: Recording">
    Pass **`ambientSessionId`** into **`useAmbientSession`**. Use **`start`**, **`pause`**, **`resume`**, and **`submit`**. Use **`sessionStatus`** for lifecycle state, and a local **`phase`** for recording versus paused. See [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook).
  </Accordion>
</AccordionGroup>

<Tip>
  Always wait for `isSuccess` before you use `ambientSessionId`. An undefined session id breaks `useAmbientSession`.
</Tip>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Manage ambient session](/headless-web-sdk/guides/hooks/ambient-session-hook) guide to add session context and improve note quality.