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.
How authentication works
Flow diagram: Below is a diagram of the authentication flow for Partner Token exchange with Suki.Flow steps
User Signs In
Partner 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.
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 assub,email, or a custom claim you registered during onboarding.
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.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.
Suki Backend Validates the Token Using Your JWKS Endpoint
Suki validates the token as follows:
- Uses your
partnerIdto 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.
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.
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.
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.
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.
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.