Skip to main content

​
Overview

This guide explains how you, as a developer, can securely authenticate to use Suki’s APIs and SDKs. It provides a detailed walkthrough of the authentication flow between your application, and the Suki for partners.

​
Prerequisites

To integrate your application with Suki for partners, you must meet the following requirements.

Authentication System

Your application must implement a secure authentication system that generates a standards-compliant JWT or is OAuth 2.0 compliant.

User Identifier

Your JWTs must include at least one consistent user identifier claim.

Public Key

You must maintain a public JWKS endpoint that the Suki platform can access to verify your tokens.

Onboarding

You must register your JWKS endpoint URL with Suki and inform Suki which user identifier field to extract from your tokens during the partner onboarding process.

​
Authentication Mechanism

Suki for partners uses a trusted, federated authentication model called token exchange. This means we rely on your application’s existing user authentication to grant secure access to Suki’s services. The entire process works by passing a partnerToken from your application to the Suki Platform during initialization. This token must be a standard JSON Web Token (JWT).

​
Authentication Flow

​
Key Concepts

​
Identity Provider (IDP)

An Identity Provider is the system that manages user identities and authenticates users for your application. When a user signs in, your IDP verifies their credentials and confirms their identity. This can be a third-party service like Okta or a service you have built internally.

​
Partner Token (JWT)

The partnerToken is a secure, digitally signed JSON Web Token (JWT) issued by your IDP after it successfully authenticates one of your users. You must pass this token to the Suki SDK or APIs during initialization. The partnerToken must be signed using the RS256 (RSA Signature with SHA-256) algorithm.

​
Required Claims

The partnerToken you provide to Suki must contain the following JWT claims:
  • exp: The expiration time of the token, as a Unix timestamp.
  • aud: The “audience” of the token.
  • iss: The “issuer” of the token.
  • User Identifier: A claim that uniquely identifies the user. This can be a standard claim like email, sub, or a custom claim like userId.
During partner onboarding, you must notify Suki which identifier field your tokens contain. Suki will configure the system to extract the correct identifier.If your tokens contain multiple identifiers, specify which one should be the primary identifier.

​
Public Key Sharing Method

This is a critical step is establishing a secure method for sharing your public key with Suki, which we use to verify the authenticity of your partnerToken. Using a JWKS URL is the most common and recommended approach.
MethodDescription
JWKS_URL(Recommended) The public key is hosted at a public JWKS URL you provide.
STORED_SECRETThe public key is securely stored as an encrypted file in Suki’s database.
OKTAThe public key is stored in Okta, and you share the issuer URL with Suki.
JWTASSERTIONThe public key is shared as a JWT signed by Suki’s private key.

​
JWKS URL

A JSON Web Key Set (JWKS) URL is a public, secure HTTPS endpoint you host where Suki can retrieve your cryptographic public keys. Suki uses these keys to confirm that the partnerToken was legitimately signed by your IDP and has not been altered. Example JWKS URL: https://sdp.suki.ai/api/auth/.well-known/jwks-pub.json

​
Example JWKS Endpoint Response:

JSON
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "sdp-pub",
      "use": "sig",
      "alg": "RS256",
      "n": "base64url-encoded-modulus",
      "e": "base64url-encoded-exponent"
    }
  ]
}

​
How To Get The JWKS URL?

If you use Okta, Auth0, AWS Cognito, Azure AD, or Google Identity, they automatically provide this URL.
  • You’ll usually find it in your IdP’s developer console -> application settings -> JWKS / OpenID Connect configuration.
  • Often, it’s under the .well-known/openid-configuration path.
  • If you still can’t find it, you can ask your IdP to provide it to you or you can watch this video to learn how to get the JWKS URL.

​
Generating The Partner Token

Using an industry-standard framework like OAuth 2.0 is the recommended approach. Your IDP (like Okta) handles the user’s login, and the user grants your application permission to access Suki on their behalf. The result is an ID Token (a JWT), which is the partnerToken you will pass to the Suki SDK. This flow is highly secure because neither Suki nor your application ever handles the user’s password directly. You can generate the required JWT using your existing infrastructure. Sample JWT:
JWT
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1In0.
eyJzdWIiOiJ1c2VyXzAwMSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImV4cCI6MTcyNDUwMDAwMH0.
TUlDSEFTdW5nU2lnbmF0dXJlRGlnaXRhbGx5U2lnbmVkV2l0aFByaXZhdGVLZXk
If you want to identify the claims from the JWT, you can use the jwt.io website.
JWT.io

​
Using A Custom JWT Provider

If you do not use an OAuth 2.0 provider, you can use your own internal authentication system to generate the required JWT, as long as it meets the claim and signing requirements outlined in this guide.
When your application gives the Suki SDK a partnerToken, Suki uses your partnerId to find your registered JWKS URL and verify the token’s signature, trusting that you have properly authenticated the user.

​
Detailed Authentication Steps

1

Initial Authentication

The process begins after a user is logged into your application.
  • Your application provides its authentication token (partnerToken) to the Suki SDK during initialization.
  • The Suki SDK forwards this partnerToken and your partnerId to the Suki Developer Platform (SDP).
2

Token Validation

When SDP receives the partnerToken, it performs the following validation steps:
  • Uses your partnerId to identify your partner configuration.
  • Retrieves your public keys from the JWKS endpoint you registered during onboarding.
  • Verifies the partnerToken’s digital signature using these public keys.
3

Suki Token Usage

Once the Suki SDK receives the Suki-specific token:
  • The SDK stores this token securely. Your application does not need to store or manage it.
  • The SDK automatically includes this token in all subsequent requests to Suki services for authorization.
  • The SDK automatically refreshes the token when needed. You can also trigger a refresh on demand by calling the setPartnerToken method when your application refreshes its own token.

​
Troubleshooting

If you encounter issues during authentication, refer to the common problems below.
Symptom: SDP returns a 400 Bad Request with the message “Missing required identifier claim”.Resolution:
  • Verify that the partnerToken includes the user identifier claim that was specified during your onboarding.
  • Ensure the identifier’s value is not empty or null.
  • Contact Suki support if your token structure has changed and requires reconfiguration.
Symptom: SDP returns a 401 Unauthorized error with the message “Token validation failed”.Resolution:
  • Verify your application is generating valid JWTs.
  • Check the token’s expiration time (exp claim) to ensure it is not expired before being passed to the SDK.
  • Ensure all required claims are present in the token.
Symptom: SDP returns a 502 Bad Gateway error or a timeout.Resolution:
  • Confirm your JWKS endpoint URL is publicly accessible over the internet.
  • Check for any firewall rules or IP restrictions that could be blocking access from Suki’s servers.
Symptom: SDP returns a 400 Bad Request with the message “Unknown partner identifier”.Resolution:
  • Verify that the partnerId you provide during SDK initialization is correct.
  • Ensure your JWKS URL registered in the Suki platform matches your actual endpoint.
Symptom: SDP returns a 400 Bad Request with the message “Malformed token”.Resolution:
  • Ensure the token follows the standard header.payload.signature JWT format.
  • Verify the token is properly Base64URL encoded.
  • Check that the signature algorithm declared in the token’s header matches the one you used to sign it (e.g., RS256).
Symptom: Authentication suddenly begins to fail after a period of working correctly.Resolution:
  • If you have rotated your signing keys, ensure your JWKS endpoint has been updated with the new public keys.
  • Verify that the Key ID (kid) in the JWT header matches one of the keys listed in your JWKS endpoint.

​
Next Steps

After you have successfully authenticated your application, you can start using the Suki SDK or APIs to access Suki’s features.