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

# Partner Authentication Flow

> Partner Token exchange flow: clinician login, JWKS validation, Suki Token, and authenticated SDK or API requests

<Info>
  The authentication flow is primarily used for Partner authentication in SDKs. For provider and user authentication against the Partner APIs, refer to [Provider authentication](/api-reference/provider-authentication) guide.
</Info>

This guide explains how to exchange a Partner Token for a Suki Token. Before you begin, complete the prerequisites in [Partner authentication](/documentation/how-to/partner-authentication), including configuring your JWKS endpoint and generating Partner Tokens.

Suki uses federated authentication. That means your identity provider authenticates the user and issues a Partner Token (JWT). You send that token to Suki. Suki verifies it using your public keys from the JWKS endpoint and returns a Suki Token. Use the Suki Token to authenticate subsequent SDK and API requests.

## How identities map in your app

Your application owns clinician authentication. Suki does not provide a separate clinician login for your users or receive their clinic passwords.

The clinician signs in through your existing identity provider (IdP). After authentication, your backend uses the **Partner Token** issued by your IdP to authenticate with Suki. Depending on the authentication mode configured for your integration, your backend may also need to provide a `provider_id` configured during onboarding.

After successful Suki Login, your application uses the **Suki Token (`sdp_suki_token`)** for subsequent authenticated REST and WebSocket calls.

### Authentication flow

The overall flow is:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827','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'}}}%%
sequenceDiagram
    participant C as Clinician
    participant App as Your application
    participant IDP as Your IdP
    participant Suki as Suki

    C->>App: Sign in
    App->>IDP: Authenticate clinician
    IDP-->>App: Partner Token (JWT)

    App->>Suki: Register / Login<br/>Partner Token + required provider context
    Suki-->>App: Suki Token (sdp_suki_token)

    C->>App: Use Ambient / Dictation / Form filling
    App->>Suki: Authenticated API request<br/>Suki Token
    Suki-->>App: Response
```

The exact fields sent to [Register](/api-reference/authentication/register) and [Login](/api-reference/authentication/login) depend on the authentication mode configured for your integration. Refer to [Standard](/api-reference/provider-authentication), [Bearer](/api-reference/bearer-partner-authentication), and [Single Auth Token](/api-reference/single-auth-token-authentication) authentication guides for more details.

### What you are building

Your authentication flow connects the signed-in clinician in your app to authenticated Suki API and SDK calls:

**Your clinician login → Partner Token → Suki Register / Login → Suki Token → Authenticated Suki API calls**

This flow applies when a clinician registers or logs in and when they later use authenticated **Ambient**, **Dictation**, or **Form filling** functionality.

### How to wire authentication into your product

| Step in your product                  | What the clinician sees                                      | What your backend does                                                                                              |
| :------------------------------------ | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| **1. Sign in**                        | Your existing login screen, such as Doctor ID, email, or SSO | Authenticate the clinician with your identity provider. **Do not send the clinician's password to Suki.**           |
| **2. After sign-in**                  | Your application home page or chart list                     | Obtain the Partner Token (JWT) from your identity provider. Call Suki Register if required, then Suki Login.        |
| **3. Suki authentication succeeds**   | The clinician continues into your application                | Store the returned `sdp_suki_token` and the provider mapping required by your configured authentication mode.       |
| **4. Clinician uses Suki features**   | The clinician uses Ambient, Dictation, or Form filling       | Send `sdp_suki_token` with authenticated REST and WebSocket requests. For Single Auth, also send `sdp_provider_id`. |
| **5. Suki Token needs to be renewed** | Your application handles re-authentication or token refresh  | Obtain a fresh Partner Token, authenticate again with Suki, and replace the Suki Token.                             |

### How the identities relate

These identifiers have different purposes. Do not treat them as interchangeable.

| Identity                                            | Owned or configured by                                                                                       | How it is used                                                                                                                                                                                       |
| :-------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Your application user**                           | Your application                                                                                             | Represents the clinician in your application and is used for your own authentication and user management.                                                                                            |
| **Partner ID**                                      | Suki onboarding                                                                                              | Identifies your integration during Suki authentication.                                                                                                                                              |
| **Partner Token (JWT)**                             | Your identity provider                                                                                       | Sent on Register and Login. For Standard auth, the token identifies the clinician. For Bearer and Single auth, the token authenticates your integration, and `provider_id` identifies the clinician. |
| **Suki Token (`sdp_suki_token`)**                   | Returned by Suki Login                                                                                       | Authenticates subsequent Suki REST and WebSocket calls.                                                                                                                                              |
| **Provider ID (`provider_id` / `sdp_provider_id`)** | Your stable clinician / provider identifier (agreed during onboarding). Required for Bearer and Single auth. | Identifies the clinician when required by the configured authentication mode.                                                                                                                        |
| **Organization ID (`provider_org_id`)**             | Your organization model / configured integration                                                             | Sent during Register when required by the configured authentication mode.                                                                                                                            |

### Authentication modes

The values your backend sends depend on the authentication mode configured for your integration.

| Auth mode    | Register and Login                     | Later API calls                          |
| :----------- | :------------------------------------- | :--------------------------------------- |
| **Standard** | Partner Token identifies the clinician | Use the Suki Token                       |
| **Bearer**   | Partner Token and `provider_id`        | Use the Suki Token                       |
| **Single**   | Partner Token and `provider_id`        | Use the Suki Token and `sdp_provider_id` |

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart LR
    A[Clinician] --> B[Your application]
    B --> C[Your IdP]
    C --> D[Partner Token]

    D --> E{Suki authentication mode}

    E -->|Standard| F[Suki Register / Login]
    E -->|Bearer| G[Suki Register / Login<br/>+ provider_id]
    E -->|Single| H[Suki Register / Login<br/>+ provider_id]

    F --> I[Suki Token]
    G --> I
    H --> I

    I --> J[Ambient / Dictation / Form filling]
    H --> K[sdp_provider_id]
    K --> J

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style H fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style I fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style J fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style K fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

The diagram shows the authentication values at a high level. Use the authentication requirements for your configured mode when implementing the actual requests. For mode details, see [Partner authentication](/documentation/how-to/partner-authentication).

### Keep provider mapping in your backend

When your authentication mode requires `provider_id`, use the stable clinician identifier agreed during onboarding. That value is your system's provider identifier (for example the ID from your EHR), not a separate Suki-issued Doctor ID.

Keep the same `provider_id` for a clinician across Register, Login, and later `sdp_provider_id` headers when your mode requires them.

For example:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart TB
    A[Signed-in clinician in your app] --> B[Your stable provider identifier]
    B --> C[provider_id on Register / Login]

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

For Standard authentication, Suki derives clinician identity from the Partner Token, so you do not send `provider_id` on Register or Login. See [Standard partner authentication](/api-reference/provider-authentication).

Your backend should also handle the Partner Token and Suki Token according to your application's authentication architecture. The Suki Token returned by Login is used for subsequent authenticated Suki requests.

For a working example of this authentication split, see the [Ambient API starter](https://github.com/LearningMotors/Suki-partner-samples/tree/main/ambient-api-starter).

## How authentication works

The diagram and steps below show the **SDK** token-exchange path (Web SDK, Mobile SDK, and similar). For Partner REST APIs, your backend calls [Register](/api-reference/authentication/register) and [Login](/api-reference/authentication/login), then sends `sdp_suki_token` on later requests. See [How identities map in your app](#how-identities-map-in-your-app) for that path.

**Flow diagram:**

Below is a diagram of the authentication flow for Partner Token exchange with Suki.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart TD
    Start([User Signs In]) --> IDP[Identity Provider<br/>authenticates user]
    IDP --> Token[IDP issues<br/>partner token JWT]
    Token --> Init[Your app initializes Suki SDK<br/>with partner token]
    Init --> Send[SDK sends partner token<br/>to Suki Backend]
    Send --> Validate[Suki Backend<br/>validates token<br/>using your JWKS endpoint]
    Validate --> Check{Token valid?}
    Check -->|No| Error[Authentication fails]
    Check -->|Yes| SukiToken[Suki Backend returns<br/>Suki-specific token]
    SukiToken --> Store[SDK stores<br/>token internally]
    Store --> Ready[SDK ready for use]
    Ready --> Feature[User requests Suki feature]
    Feature --> Call[App calls<br/>SDK method]
    Call --> Auth[SDK makes authorized request<br/>to Suki Backend]
    Auth --> Response[Suki Backend<br/>returns result]
    Response --> Display[SDK returns<br/>result to app]
    Display --> End([Complete])

    style Start fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style IDP fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Token fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Init fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Send fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Validate fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Check fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Error fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style SukiToken fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Store fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Ready fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Feature fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Call fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Auth fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Response fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style Display fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style End fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

## Flow steps

These steps follow the **SDK** path. Partner API integrations use Register and Login from your backend instead of SDK initialization. See [Provider authentication](/api-reference/provider-authentication).

<Steps>
  <Step title="User Signs In" icon="user">
    The clinician signs in to your application using your identity provider. After successful authentication, your IDP issues a JWT token (`partnerToken`).

    <Note>
      Suki does not handle user logins directly. Your IDP verifies the user's credentials and confirms their identity. The IDP can be a third-party service such as Okta or Azure AD, or a system you built yourself.
    </Note>
  </Step>

  <Step title="Identity Provider Issues a Partner Token JWT" icon="shield-check">
    After successful sign-in, your IDP issues a JWT. In the Suki integration this JWT is the **`partnerToken`** (Partner Token). It must be a standard JWT that Suki can verify with your public keys.

    **Token requirements:**

    * Signed with the **RS256** algorithm.
    * Issued by your identity provider after user authentication.
    * Includes user identifier claims that Suki can verify.
    * Includes **`exp`**, **`iss`**, **`aud`**, and a user identifier claim such as **`sub`**, **`email`**, or a custom claim you registered during onboarding.

    <Tip>
      During onboarding you tell Suki which identifier field your tokens use. If a token has multiple identifiers, you specify which one is **primary**.
    </Tip>
  </Step>

  <Step title="Your App Initializes the Suki SDK with the Partner Token" icon="rocket">
    Your application initializes the Suki SDK with the **`partnerToken`** and your **`partnerId`**. The SDK sends these values to Suki's backend for validation. You use your existing authentication system for the user; Suki trusts that system through token exchange rather than creating separate user accounts.
  </Step>

  <Step title="SDK Sends the Partner Token to the Suki Backend" icon="arrow-right">
    The SDK forwards the Partner Token to Suki so the backend can validate it before any Suki feature runs.
  </Step>

  <Step title="Suki Backend Validates the Token Using Your JWKS Endpoint" icon="shield-check">
    Suki validates the token as follows:

    * Uses your **`partnerId`** to find your partner configuration.
    * Fetches your public keys from your registered JWKS endpoint (or another public-key sharing method you configured during onboarding).
    * Verifies the token's digital signature with those keys.
    * Confirms the token has not expired and contains the required claims.

    <Note>
      If validation succeeds, Suki returns a Suki-specific token. This is the token the SDK uses after the exchange. It is separate from the Partner Token your IDP issued.
    </Note>
  </Step>

  <Step title="SDK Stores the Token Internally" icon="key">
    The SDK stores the Suki-specific token securely (you do not manage it yourself) and automatically includes it in API requests. It refreshes it automatically when needed.
  </Step>

  <Step title="SDK Ready for Use" icon="check-circle">
    After the Suki-specific token is stored, the SDK is ready. Your application can use Suki APIs and SDKs. The SDK handles token management for subsequent calls.
  </Step>

  <Step title="User Requests a Suki Feature and the App Calls an SDK Method" icon="arrow-right">
    When the user requests a Suki feature, your app calls the relevant SDK method. The diagram shows this as the path from a ready SDK into feature usage.
  </Step>

  <Step title="SDK Makes an Authorized Request to the Suki Backend" icon="arrow-right">
    The SDK sends an authorized request to the Suki backend using the stored Suki-specific token. You do not pass the Partner Token again on every feature call once the exchange has succeeded and the SDK is managing the Suki token.
  </Step>

  <Step title="Suki Backend Returns a Result; SDK Returns It to the App" icon="arrow-right">
    The Suki backend returns the result of the request. The SDK returns that result to your application, which completes the flow for that feature call.
  </Step>
</Steps>

## Available cookbooks

<div className="hp-io-method-grid tut-hub-card-grid" data-cookbook-related-grid>
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/register-then-login">
    <div className="tut-hub-card-media tut-hub-card-media--blue" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Authentication</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--api">API</span>
      </div>

      <h3 className="hp-io-method-card-title">Register Provider Then Login</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Register first, then call login.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>

  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/bearer-provider-id-on-login">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Authentication</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--api">API</span>
      </div>

      <h3 className="hp-io-method-card-title">Add provider\_id to Bearer Login</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Send provider\_id on Bearer login.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Start building with the [Web SDK](/web-sdk/overview) or [Mobile SDK](/mobile-sdk/overview) and start integrating Suki features into your application.

<Icon icon="file-lines" iconType="solid" /> Understand which path is best for you by reading the [Integration paths overview](/documentation/get-started/integration-overview).