​
Suki SDK Authentication Documentation

​
Overview

This document describes the authentication flow between the Partner applications, Suki SDK and the Suki Developer Platform (SDP). The system implements a federated authentication approach where the Suki SDK leverages existing user authentication from the Partner application to establish secure access to Suki services. SDK authentication process kicks in as soon as SDK is initialized, there is no explicit method invokation.

​
Key Definitions

​
1. partnerToken

The partnerToken is a JSON Web Token (JWT) issued by the Partner’s Identity Provider (IDP) that verifies a user’s authenticated status within the Partner application.

  • Partner token must be passed to SDK during initialization.

Required Claims:

  • exp: Expiration timestamp (Unix time)
  • aud: Audience (string or array)
  • iss: Issuer (string or URI)

User Identifier: The partnerToken must include some user identifier, it can be ONE of the following identifier fields or any arbitrary field that represents the user uniquely in your system:

  • email: The user’s email address
  • username: The user’s username
  • userId: A persistent unique identifier for the user
  • sub: Can also serve as the user identifier if not using other fields

Important Note: 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.

The partnerToken must be signed using either RS256 (RSA Signature with SHA-256).

​
2. partnerId

The partnerId is a unique identifier assigned by Suki to each integrated Partner application. This identifier:

  • Is provided during the Partner onboarding process
  • Links the Partner application to its configuration in the Suki Developer Platform
  • Determines which JWKS endpoint URL will be used for token validation
  • Establishes the permission mapping between Partner roles and Suki capabilities
  • Must be included in SDK initialization parameters

​
3. JWKS (JSON Web Key Set)

The JWKS is a standardized format for representing cryptographic keys as a JSON object. In the context of Suki SDK authentication:

  • It contains the public keys used to verify the digital signatures on partnerTokens
  • It must be hosted at a public HTTPS endpoint provided by the Partner
  • It follows the RFC 7517 standard format
  • It should be regularly rotated according to security best practices
  • It must contain keys that correspond to the signing algorithms used for the partnerTokens

Example JWKS format:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "base64-encoded-modulus",
      "e": "base64-encoded-exponent"
    }
  ]
}

​
Authentication Flow

​
Authentication Process Diagram

​
Flow Description

  1. The user logs into the Partner application
  2. The Partner application authenticates the user through its Identity Provider (IDP)
  3. The Partner IDP returns a partnerToken containing the user identifier
  4. When the user requests Suki functionality, the Partner app initializes the Suki SDK with the partnerToken
  5. The Suki SDK forwards the partnerToken and partnerId to the Suki Developer Platform (SDP)
  6. SDP validates the token against the Partner’s JWKS endpoint
  7. SDP extracts the configured user identifier from the token
  8. If validation succeeds, SDP returns an authentication token to the SDK
  9. The Suki SDK informs the Partner app of successful authentication
  10. The Partner app enables Suki functionality for the user
  11. When the user requests a Suki feature, the SDK handles the request using the authentication token
  12. SDP processes the request and returns the appropriate response
  13. The SDK passes the result back to the Partner app, which displays it to the user

​
1. Initial Authentication Process

The authentication process begins when a user, already logged into the Partner application, initiates an interaction requiring Suki SDK functionality.

  1. The Partner application provides its authentication token (partnerToken) to the Suki SDK.
  2. The Suki SDK forwards this partnerToken along with the partnerId to the Suki Developer Platform (SDP).
  3. SDP validates the partnerToken by verifying its signature against the Partner’s Identity Provider (IDP) JSON Web Key Set (JWKS) endpoint.
  4. SDP extracts the user identifier based on the configuration established during partner onboarding.
  5. Upon successful validation, SDP generates an authentication token for the SDK.
  6. This authentication token is returned to the SDK for subsequent API requests.

​
2. Token Validation Process

When SDP receives the partnerToken, it performs the following validation steps:

  1. Identifies the Partner configuration using the provided partnerId.
  2. Retrieves the Partner’s public keys from their registered JWKS endpoint.
  3. Verifies the partnerToken’s digital signature using these public keys.
  4. Validates token expiration and other standard claims.
  5. Extracts the configured user identifier claim from the token.
  6. Maps user identity and permission information for creating the authentication token.

​
3. Authentication Token Usage

After receiving the authentication token:

  1. The Suki SDK stores this token securely. Partner app doesn’t need to store Suki token.
  2. All subsequent requests to Suki services include this token for authorization.
  3. The token is automatically refreshed when needed, based on its expiration time or it can be refreshed on demand by invoking the setPartnerToken method whenever Partner App refreshes its token.

​
Implementation Requirements

​
Partner Application Requirements

The Partner application must:

  • Implement a secure authentication system with a standards-compliant JWT IdToken.
  • Include at least one consistent user identifier in the JWT claims.
  • Maintain a public JWKS endpoint that SDP can access to verify tokens.
  • Register the JWKS endpoint URL with Suki during onboarding.
  • Inform Suki which user identifier field to extract during configuration.

​
Troubleshooting

​
Common Authentication Issues

​
Missing Configured User Identifier

Symptoms: SDP returns a 400 Bad Request with message “Missing required identifier claim” Resolution:

  1. Verify the Partner JWT includes the user identifier claim that was specified during onboarding
  2. Ensure the identifier value is not empty or null
  3. Contact Suki support if your token structure has changed and requires reconfiguration

​
Invalid or Expired partnerToken

Symptoms: SDP returns a 401 Unauthorized error with message “Token validation failed” Resolution:

  1. Verify the Partner application is generating valid JWTs
  2. Check token expiration time - it may need to be refreshed before passing to Suki SDK
  3. Ensure all required claims are present in the token (exp, iat)

​
JWKS Endpoint Connectivity Issues

Symptoms: SDP returns a 502 Bad Gateway error or timeout Resolution:

  1. Confirm the Partner IDP JWKS endpoint is publicly accessible
  2. Verify network connectivity between SDP and the Partner IDP
  3. Check for any IP restrictions or firewall rules blocking access

​
Partner Configuration Issues

Symptoms: SDP returns a 400 Bad Request with message “Unknown partner identifier” Resolution:

  1. Verify the Partner ID is correctly configured in both the SDK initialization and SDP
  2. Ensure the Partner has been properly onboarded to the Suki platform
  3. Check that the registered JWKS endpoint URL in SDP matches the actual endpoint

​
Token Format Problems

Symptoms: SDP returns a 400 Bad Request with message “Malformed token” Resolution:

  1. Ensure the token follows the JWT standard format (header.payload.signature)
  2. Verify the token is properly encoded (Base64URL encoding)
  3. Check that the token’s signature algorithm matches what’s declared in the header

​
Key Rotation Issues

Symptoms: Previously working tokens suddenly fail validation Resolution:

  1. Verify the JWKS endpoint still contains the key used to sign the tokens
  2. Check if keys have been rotated and update the JWKS endpoint accordingly
  3. Ensure the ‘kid’ (Key ID) in the JWT header matches a key in the JWKS