Partner Authentication Flow

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

The authentication flow is primarily used for Partner authentication in SDKs. For provider and user authentication against the Partner APIs, refer to Provider authentication guide.

This guide explains how to exchange a Partner Token for a Suki Token. Before you begin, complete the prerequisites in 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:

The exact fields sent to Register and Login depend on the authentication mode configured for your integration. Refer to Standard, Bearer, and Single Auth Token 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

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.

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:

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.

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.

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 and Login, then sends sdp_suki_token on later requests. See 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.

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.

1. User Signs In

   The clinician signs in to your application using your identity provider. After successful authentication, your IDP issues a JWT token (partnerToken).

   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.

2. Identity Provider Issues a Partner Token JWT

   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.

   During onboarding you tell Suki which identifier field your tokens use. If a token has multiple identifiers, you specify which one is primary.

3. Your App Initializes the Suki SDK with the Partner Token

   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.

4. SDK Sends the Partner Token to the Suki Backend

   The SDK forwards the Partner Token to Suki so the backend can validate it before any Suki feature runs.

5. Suki Backend Validates the Token Using Your JWKS Endpoint

   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.

   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.

6. SDK Stores the Token Internally

   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.

7. SDK Ready for Use

   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.

8. User Requests a Suki Feature and the App Calls an SDK Method

   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.

9. SDK Makes an Authorized Request to the Suki Backend

   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.

10. Suki Backend Returns a Result; SDK Returns It to the App

    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.

Available cookbooks

AuthenticationAPI

Register Provider Then Login

Register first, then call login.

5 min

AuthenticationAPI

Add provider_id to Bearer Login

Send provider_id on Bearer login.

5 min

Next steps

Start building with the Web SDK or Mobile SDK and start integrating Suki features into your application.

Understand which path is best for you by reading the Integration paths overview.