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

> JWT-based authentication implementation for Suki platform partners

<Callout icon="handshake" color="orange">
  **Are you a Suki partner?**

  To use any of our APIs or SDKs, you must be a Suki partner. Contact our partnership team to get started with the onboarding process. They will help you set up your authentication system and get you started with the Suki APIs and SDKs.

  <div style={{ marginTop: '0.75rem' }}>
    <a className="hp-cta hp-cta-secondary hp-cta-with-icon" href="https://www.suki.ai/suki-partners/" target="_blank" rel="noopener noreferrer">
      Contact Partnership Team

      <svg className="hp-cta-icon" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <path d="M7 7h10v10" />

        <path d="M7 17 17 7" />
      </svg>
    </a>
  </div>
</Callout>

This guide explains how Suki uses your existing authentication system to authenticate your application to use Suki's APIs and SDKs. You'll use your existing authentication system; Suki doesn't handle user logins directly. You'll use a <Tooltip tip="A secure, digitally signed JWT issued by a partner's identity provider after user authentication, passed to Suki SDK for user verification." cta="View in Glossary" href="/Glossary/p">Partner Token</Tooltip> (JWT) that your identity provider issues after user sign-in.

## Prerequisites

Before you begin, ensure you have:

<CardGroup cols={2}>
  <Card title="Authentication System" icon="shield-check">
    An authentication system that generates standards-compliant JWTs or is OAuth 2.0 compliant.
  </Card>

  <Card title="User Identifier" icon="user">
    JWTs that include at least one consistent user identifier claim (like `sub` or `email`).
  </Card>

  <Card title="Public Key Endpoint" icon="link">
    A publicly accessible <Tooltip tip="JSON Web Key Set. A set of keys containing the public keys used to verify any JWT issued by the authorization server." cta="View in Glossary" href="/Glossary/j">JWKS</Tooltip> endpoint where Suki can fetch your public keys to verify tokens.
  </Card>

  <Card title="Completed Onboarding" icon="handshake">
    Completed [Partner onboarding](/documentation/partner-onboarding) and registered your JWKS endpoint URL with Suki.
  </Card>
</CardGroup>

<Note>
  Already a Suki partner and looking for how to authenticate providers and users to use the Suki APIs? Refer to [Provider authentication](/api-reference/provider-authentication) for more details.
</Note>

## How authentication works

Suki uses a federated authentication model called **token exchange**. Instead of creating separate user accounts, Suki trusts your existing authentication system.

**The process:**

1. A user signs in to your application using your identity provider
2. Your system generates a JWT token for that user
3. You send this token (called `partnerToken`) to Suki when initializing APIs or SDKs
4. Suki verifies the token using your public keys and grants access

The `partnerToken` must be a standard <Tooltip tip="JSON Web Token. A compact, URL-safe means of representing claims used for authentication and information exchange." cta="View in Glossary" href="/Glossary/j">JWT</Tooltip> that Suki can verify using your public keys.

### Authentication flow

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

## Key concepts

### Identity provider (IDP)

An Identity Provider is the system that handles user authentication for your application. When users sign in, your IDP verifies their credentials and confirms their identity. This can be a third-party service like **Okta** or **Azure AD**, or a system you built yourself.

### Partner Token (JWT)

The `partnerToken` is a JWT (JSON Web Token) that your identity provider creates after successfully authenticating a user. You pass this token to Suki's SDKs or APIs during initialization to prove the user's identity.

**Requirements for the Partner Token:**

* Must be signed using the [RS256 algorithm](https://www.techtarget.com/searchsecurity/definition/RSA) (RSA Signature with SHA-256)
* Must be issued by your identity provider after user authentication
* Must include user identifier claims that Suki can verify

**Required claims for the Partner Token:**

The `partnerToken` you provide to Suki must include one or more of these JWT claims:

* **`exp`** - Token expiration time (Unix timestamp). The token must not be expired when you send it to Suki.
* **`iss`** - Token issuer (usually your identity provider's URL or identifier).
* **`aud`** - Token audience (who the token is intended for).
* **User Identifier** - A claim that uniquely identifies the user, such as `sub`, `email`, or a custom claim like `userId`.

<Note>
  During onboarding, you must inform Suki which **identifier field** your tokens use. If your tokens have multiple identifiers, **specify** which one is the **primary identifier**.
</Note>

## Public key sharing methods

Suki needs your public keys to verify your tokens. Choose one of these methods to share them:

| Method             | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| **JWKS\_URL**      | (Recommended) Host your public keys at a public JWKS URL endpoint.     |
| **STORED\_SECRET** | Share your public key with Suki; we store it securely in our database. |
| **OKTA**           | Use Okta as your identity provider; share your Okta issuer URL.        |
| **JWTASSERTION**   | Share your public key as a JWT signed by Suki's private key.           |

### JWKS URL (recommended)

A JWKS (JSON Web Key Set) URL is a public HTTPS endpoint where Suki can fetch your public keys. Suki uses these keys to verify that your `partnerToken` was signed by your identity provider and hasn't been tampered with.

**Example JWKS URL:** `https://sdp.suki-stage.com/api/auth/.well-known/jwks-pub.json`

**Example JWKS Response:**

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "sdp-pub",
      "use": "sig",
      "alg": "RS256",
      "n": "base64url-encoded-modulus",
      "e": "base64url-encoded-exponent"
    }
  ]
}
```

### How to find your JWKS URL

If you use Okta, Auth0, AWS Cognito, Azure AD, or Google Identity, they provide this URL automatically.

**Where to find it:**

* Check your identity provider's developer console → application settings → **JWKS** or **OpenID Connect configuration**
* Often available at: `https://your-idp-domain/.well-known/openid-configuration`
* If you can't find it, contact your identity provider or watch this [Tutorial video](https://www.youtube.com/watch?v=biv2kFFjsfE)

## Generating the Partner Token

### Use OAuth 2.0 / OpenID Connect (recommended)

Using OAuth 2.0 or OpenID Connect is the recommended approach. Your identity provider (like Okta or Azure AD) handles user login and issues an ID token (a JWT). This ID token becomes your `partnerToken` that you pass to Suki.

**Why this is secure:**

* Your identity provider handles authentication
* Neither Suki nor your app handles user passwords
* Tokens are cryptographically signed and verified

**Sample JWT:**

```JWT theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1In0.
eyJzdWIiOiJ1c2VyXzAwMSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImV4cCI6MTcyNDUwMDAwMH0.
TUlDSEFTdW5nU2lnbmF0dXJlRGlnaXRhbGx5U2lnbmVkV2l0aFByaXZhdGVLZXk
```

<Tip>
  Use [jwt.io](https://jwt.io/) to decode and inspect JWT tokens. Paste your token to see its claims and verify the structure.

  <Frame>
    <img src="https://mintcdn.com/suki-1e08f176/zZGEkUTIkO3Bt4sD/documentation/assets/jwt.webp?fit=max&auto=format&n=zZGEkUTIkO3Bt4sD&q=85&s=88b1de7a5578b4a9da74637ba4a794c5" alt="JWT.io" loading="eager" decoding="async" width="1400" height="541" data-path="documentation/assets/jwt.webp" />
  </Frame>
</Tip>

### Using a custom authentication system

If you don't use OAuth 2.0, you can generate JWTs with your own authentication system. Make sure your tokens meet the requirements in this guide:

* Signed with RS256 algorithm
* Include all required claims
* Properly formatted as a standard JWT

<Note>
  When you pass a `partnerToken` to Suki, we use your `partnerId` to find your registered JWKS URL and verify the token's signature. We trust that you've properly authenticated the user.
</Note>

## Authentication flow steps

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

  <Step title="Initialize SDK" icon="rocket">
    Your application initializes the Suki SDK with the `partnerToken` and your `partnerId`. The SDK sends these to Suki's backend for validation.
  </Step>

  <Step title="Token validation" icon="shield-check">
    Suki validates your token:

    * Uses your `partnerId` to find your partner configuration
    * Fetches your public keys from your registered JWKS endpoint
    * Verifies the token's digital signature using those keys
    * Confirms the token hasn't expired and contains required claims
  </Step>

  <Step title="Receive Suki token" icon="key">
    If validation succeeds, Suki returns a Suki-specific token. The SDK:

    * Stores this token securely (you don't need to manage it)
    * Automatically includes it in all API requests
    * Refreshes it automatically when needed
  </Step>

  <Step title="Ready to use" icon="check-circle">
    Your application can now use Suki's APIs and SDKs. The SDK handles token management automatically.
  </Step>
</Steps>

## Troubleshooting

Common authentication issues and how to fix them:

<Accordion title="Missing User Identifier">
  **Error:** 400 Bad Request - "Missing required identifier claim"

  **Fix:**

  * Check that your `partnerToken` includes the user identifier claim you specified during onboarding
  * Ensure the identifier value is not empty or null
  * If your token structure changed, contact [Suki support](https://forms.suki.ai/SukiSupport/form/SukiSDKSupport/formperma/T3z7hYJ7Ph-J7JrWSN08QJn32BYjarkxqm8Lm8XFPow) to update your configuration
</Accordion>

<Accordion title="Invalid or Expired Token">
  **Error:** 401 Unauthorized - "Token validation failed"

  **Fix:**

  * Verify your application generates valid JWTs
  * Check the `exp` claim to ensure the token hasn't expired
  * Confirm all required claims (`exp`, `iss`, `aud`, user identifier) are present
  * Use [jwt.io](https://jwt.io/) to decode and inspect your token
</Accordion>

<Accordion title="JWKS Endpoint Not Accessible">
  **Error:** 502 Bad Gateway or timeout

  **Fix:**

  * Ensure your JWKS endpoint URL is publicly accessible over HTTPS
  * Check firewall rules or IP restrictions that might block Suki's servers
  * Test the URL in a browser or with `curl` to confirm it's reachable
</Accordion>

<Accordion title="Wrong Partner ID">
  **Error:** 400 Bad Request - "Unknown partner identifier"

  **Fix:**

  * Verify the `partnerId` you're using matches the one Suki provided during onboarding
  * Check that your JWKS URL in Suki's system matches your actual endpoint URL
</Accordion>

<Accordion title="Malformed Token">
  **Error:** 400 Bad Request - "Malformed token"

  **Fix:**

  * Ensure the token follows standard JWT format: `header.payload.signature`
  * Verify the token is properly Base64URL encoded
  * Check that the `alg` in the header matches your signing algorithm (should be RS256)
</Accordion>

<Accordion title="Key Rotation Issues">
  **Error:** Authentication fails after previously working

  **Fix:**

  * If you rotated your signing keys, update your JWKS endpoint with the new public keys
  * Verify the `kid` (Key ID) in your JWT header matches a key in your JWKS endpoint
  * Ensure old keys remain available during the transition period
</Accordion>

## Next steps

Once authentication is working, you're ready to integrate Suki's features:

<Icon icon="file-lines" iconType="solid" /> **[Web SDK](/web-sdk/overview)** - Add pre-built UI components to your web application

<Icon icon="file-lines" iconType="solid" /> **[Mobile SDK](/mobile-sdk/overview)** - Integrate ambient intelligence into iOS apps

<Icon icon="file-lines" iconType="solid" /> **[Headless Web SDK](/headless-web-sdk/introduction)** - Build custom UIs with React hooks

<Icon icon="file-lines" iconType="solid" /> **[API reference](/api-reference/overview)** - Use REST APIs for maximum flexibility