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

> Learn how the flow works for Partner authentication. Includes a step-by-step token exchange flow: partner JWT, JWKS validation, Suki token, and authorized SDK 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) guide, including configuring your JWKS endpoint and generating Partner Tokens.

Suki uses federated authentication means that 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 authentication works

**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"}}
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])

    classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
    classDef tokenStyle fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#000000
    classDef readyStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000

    class IDP,Init,Send,Validate authStyle
    class Token,SukiToken,Store tokenStyle
    class Ready readyStyle
```

## Flow steps

<Steps>
  <Step title="User Signs In" icon="user">
    Partner 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>

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