Skip to main content

​
Overview

This guide explains how you, as a developer or partner, can use Suki’s APIs and SDKs. It also walks through the authentication flow between your application, the Suki SDK, and APIs.

​
Prerequisites

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

​
Application requirements

Your application must:
  • Implement a secure authentication system that generates a standards-compliant JWT or should be OAuth 2.0 compliant.
  • Include at least one consistent user identifier in the JWT claims.
  • Maintain a public JWKS endpoint that the Suki platform can access to verify your tokens.
  • Register your JWKS endpoint URL with Suki during the partner onboarding process.
  • Inform Suki which user identifier field to extract from your tokens during the configuration process.

​
Key Concepts

​
Identity Provider (IDP)

An Identity Provider is a system that manages user identities and authenticates users for your application. When a user logs in, your IDP verifies their credentials (like a username and password) and, upon success, 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. This token is proof that the user is who they say they are. You must pass this token to the Suki SDK during initialization. It contains verifiable information (claims) about the user and the token itself, such as an expiration time. The partnerToken must be signed using the RS256 (RSA Signature with SHA-256) algorithm.

​
Partner Token Requirements

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, which can be a string or an array of strings.
  • iss: The “issuer” of the token, which should be a string or URI that identifies your IDP.
  • User Identifier: The token must contain a claim that uniquely identifies the user. This can be a standard claim like email, sub, or a custom claim like userId or username. You must notify Suki which claim to use as the primary user identifier.
During partner onboarding, notify Suki which identifier field your tokens contain.Suki will configure the system to extract the correct identifier from your tokens. If your tokens contain multiple identifiers, specify which one should be the primary identifier for user recognition.

​
Public key sharing methods

A critical step in the integration process is establishing a secure method for sharing your public key with Suki. This key is essential for verifying the authenticity of your partnerToken. While Suki supports several methods, using a JWKS_URL is the most common and recommended approach due to its adherence to open standards and ease of key rotation. The rest of this guide focuses primarily on the JWKS_URL method. You will finalize your chosen method with the Suki team during the onboarding process. The table below outlines all available options.
MethodDescription
STORED_SECRETThe public key is securely stored as an encrypted file in Suki’s database
JWKS_URL(Recommended)The public key is hosted at a public JWKS URL you provide.
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) is a set of cryptographic public keys shared in a standard JSON format. The JWKS URL is the public, secure HTTPS endpoint you host where Suki can retrieve these keys. Your partnerToken (JWT) is signed using a private key that only your system controls. To verify that this token is authentic and has not been altered, Suki must use the corresponding public key. The JWKS URL provides a standard, secure way for Suki to access that key and confirm that the partnerToken was legitimately signed by your IDP.

​
Example JWKS URL

bash
https://sdp.suki.ai/api/auth/.well-known/jwks-pub.json
The JWKS URL is simply the endpoint (URL) where the public keys are published.

​
Example JWKS endpoint response

{
  "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.

​
Authentication Model

Suki 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 process works by passing a partnerToken to the Suki SDK during initialization. This token must be a standard JSON Web Token (JWT).

​
Generating the partnerToken

You can generate the required JWT using your existing infrastructure. The most common methods are using an OAuth 2.0 provider or a custom authentication service.
Here’s a sample JWT:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1In0.
eyJzdWIiOiJ1c2VyXzAwMSIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImV4cCI6MTcyNDUwMDAwMH0.
TUlDSEFTdW5nU2lnbmF0dXJlRGlnaXRhbGx5U2lnbmVkV2l0aFByaXZhdGVLZXk
Using an industry-standard framework like OAuth 2.0 and OpenID Connect (OIDC) is the recommended approach for generating the partnerToken.
  • The Importance of OAuth: The primary benefit of OAuth 2.0 is secure delegated authorization. In this flow, your Identity Provider (like Okta or Auth0) handles the user’s login. The user then grants your application permission to access Suki on their behalf. The result is an ID Token, a JWT that proves the user’s identity to Suki-without your application or Suki ever needing to handle the user’s password directly.
  • When using this method, the ID Token you receive from your provider is the partnerToken you will pass to the Suki SDK.

​
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 the user has been properly authenticated by you.

​
The Authentication Flow

​
High-Level Sequence Diagram

​
Detailed Authentication Steps

​
1. Initial Authentication

The process begins when a user, who is already logged into your application, requests a feature that requires the Suki SDK.
  • 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).
  • SDP validates the partnerToken by verifying its signature against your public key.
Upon successful validation, SDP generates a Suki-specific authentication token and returns it to the SDK.

​
2. Token Validation

When SDP receives the partnerToken, it performs the following validation steps:
  • Uses the 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.
  • Validates the token’s expiration and other standard claims.
  • Extracts the user identifier from the token based on the field you specified during onboarding.

​
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 the Suki token.
  • 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.
⌘I