@sumsub/id-connect

Sumsub ID Connect

Sumsub ID Connect is a JavaScript library that provides OAuth authorization with Sumsub ID. It allows you to easily integrate Sumsub ID authorization into your web applications.

Table of Contents

• Features
• Installation
• Terminology
• Usage
  • Basic Usage
  • UMD Build
• API Reference
  • openModal
  • createButton
  • Types
• Backend Integration
  • Getting a Sumsub ID Connect Token
  • Getting a Sumsub ID Share Token
  • Getting a SDK Access Token
• Examples
  • Basic Integration
• Changelog
• License
• Browser Compatibility
• Support

Features

• 🔒 Secure OAuth authorization with Sumsub ID
• 🎨 Customizable button for authorization
• 🚀 Simple API with TypeScript support
• 📱 Responsive design that works on all devices
• 🔄 Automatic handling of authorization flow

Installation

You can install the package using npm, yarn, or pnpm:

# Using npm
npm install @sumsub/id-connect

# Using yarn
yarn add @sumsub/id-connect

# Using pnpm
pnpm add @sumsub/id-connect

Terminology

This section defines key terms used throughout the documentation:

• Authorization code: A short-lived code received on the frontend after user authorization. This code is exchanged for a Sumsub ID Connect token on your backend.

• Sumsub ID Connect token: A long-lived token that allows client1 to make requests to Sumsub for generating Sumsub ID Share Tokens. This token is obtained by exchanging the authorization code.

• Sumsub ID Share Token: A token for accessing Sumsub ID, generated by client1 and passed to client2. Client2 uses this token to generate a SDK Access token for running the SDK and sharing documents.

• SDK Access token: The final token used to launch WebSDK2 via npm package. This token is generated by client2 using the Sumsub ID Share Token received from client1.

Usage

Basic Usage

This library implements the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange). When authorization is successful, the onSuccess callback receives an authorization code that must be exchanged for tokens by your backend service.

Important: The authorization code is short-lived and should be exchanged for tokens as soon as possible.

OAuth Flow

• Initialization: The library prepares the authorization flow with your client ID and optional security parameters
• Authorization: A popup window opens where the user authorizes with Sumsub ID
• Authorization Code: Upon success, your app receives an authorization code via the onSuccess callback
• Token Exchange: Your backend exchanges this code for tokens (see Backend Integration)
• Using the Tokens: Your backend uses these tokens to access Sumsub ID APIs

For security reasons, all token exchange operations should be performed on your backend, never in the browser.

There are two main ways to use this library:

1. Using the pre-built button

import { createButton } from '@sumsub/id-connect';

createButton({
  clientId: 'your-client-id',
  container: document.getElementById('button-container'),
  onSuccess: (response) => console.log('Authorization successful:', response.code),
  onError: (error) => console.error('Authorization error:', error.message),
  className: 'custom-button-class',
  text: 'Sign in with Sumsub ID'
});

2. Using your own button with the modal

import { openModal } from '@sumsub/id-connect';

document.getElementById('your-custom-button').addEventListener('click', () => {
  openModal({
    clientId: 'your-client-id',
    onSuccess: (response) => console.log('Authorization successful:', response.code),
    onError: (error) => console.error('Authorization error:', error.message),
    onLoading: (isLoading) => console.log('Loading state:', isLoading)
  });
});

UMD Build

You can also use the UMD build by including it directly in your HTML:

<script src="https://unpkg.com/@sumsub/id-connect/dist/index.umd.js"></script>
<script>
  SumsubIdConnect.createButton({
    clientId: 'your-client-id',
    container: document.getElementById('button-container'),
    onSuccess: (response) => console.log('Authorization successful:', response.code),
    onError: (error) => console.error('Authorization error:', error.message)
    // onLoading is automatically managed by the button
  });
</script>

API Reference

openModal(options)

Opens a popup window for OAuth authorization with Sumsub ID.

Parameters

• options (Object):
  • clientId (string): Your Sumsub ID client id
  • onSuccess (function): Callback function that receives the authorization response
  • onError (function, optional): Callback function that receives any errors
  • onLoading (function, optional): Callback function that receives a boolean indicating loading state
  • state (string, optional): OAuth state parameter for security
  • codeChallenge (string, optional): PKCE code challenge
  • baseUrl (string, optional): Custom base URL for the OAuth server

Returns

Void. The function opens a popup window and handles the authorization flow through callbacks.

Example

openModal({
  clientId: 'your-client-id',
  onSuccess: (response) => console.log('Authorization successful:', response.code),
  onError: (error) => console.error('Authorization error:', error.message),
  onLoading: (isLoading) => console.log('Loading state:', isLoading),
  state: 'random-state-string', // Optional
  codeChallenge: 'code-challenge-string' // Optional
});

createButton(options)

Creates a button that triggers the OAuth authorization flow when clicked.

Parameters

• options (Object):
  • clientId (string): Your Sumsub ID client id
  • container (HTMLElement): The HTML element where the button will be appended
  • onSuccess (function): Callback function that receives the authorization response
  • onError (function, optional): Callback function that receives any errors
  • onLoading (function, optional): Callback function for loading state (automatically managed by the button)
  • className (string, optional): CSS class name for styling the button
  • text (string, optional): Button text (default: 'Connect')
  • state (string, optional): OAuth state parameter for security
  • codeChallenge (string, optional): PKCE code challenge
  • baseUrl (string, optional): Custom base URL for the OAuth server

Returns

Void. The function creates a button in the specified container and sets up the authorization flow.

Example

createButton({
  clientId: 'your-client-id',
  container: document.getElementById('button-container'),
  onSuccess: (response) => console.log('Authorization successful:', response.code),
  onError: (error) => console.error('Authorization error:', error.message),
  className: 'custom-button',
  text: 'Login with Sumsub ID'
  // onLoading is automatically managed by the button
});

Types

AuthorizeResponse

The response object received after successful authorization.

type AuthorizeResponse = {
  code?: string;  // Authorization code
  state?: string; // State parameter (if provided in the request)
};

Backend Integration

Requirements

To integrate with Sumsub ID Connect, you need to:

• Have a client-key (client ID) enabled for Sumsub ID Connect
• Ask Sumsub support to enable the feature for your key (this will be a setting in the dashboard in the future)

Getting a Sumsub ID Connect Token

Exchange the authorization code for a Sumsub ID Connect token on your backend:

Endpoint: /resources/snsId/api/connect/token
Method: POST
Request Body:

{
  "code": "authorization_code_from_frontend",
  "codeVerifier": "code_verifier_used_during_authorization"
}

Response: { "token": "sumsub_id_connect_token_value" }

Example (cURL):

curl -X POST https://api.sumsub.com/resources/snsId/api/connect/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization_code_from_frontend",
    "codeVerifier": "code_verifier_used_during_authorization"
  }'

Getting a Sumsub ID Share Token

Use the Sumsub ID Connect token to obtain a Sumsub ID Share Token (generated by client1 for client2):

Endpoint: /resources/accessTokens/sumsubIdShareToken
Method: POST
Request Body:

{
  "forClientId": "client2_id",
  "sumsubIdConnectToken": "sumsub_id_connect_token_from_previous_step"
}

Response: { "token": "sumsub_id_share_token_value" }

Example (cURL):

curl -X POST https://api.sumsub.com/resources/accessTokens/sumsubIdShareToken \
  -H "Content-Type: application/json" \
  -d '{
    "forClientId": "client2_id",
    "sumsubIdConnectToken": "sumsub_id_connect_token_from_previous_step"
  }'

Getting a SDK Access Token

After client2 receives the Sumsub ID Share Token from client1, they can generate a SDK Access token:

Endpoint: /resources/accessTokens/sdk
Method: POST
Request Body:

{
  "userId": "unique_user_identifier",
  "levelName": "verification_level_name",
  "sumsubIdShareToken": "sumsub_id_share_token_from_client1"
}

Response: { "token": "sdk_access_token_value" }

Example:

async function getSdkToken(levelName, sumsubIdShareToken) {
  return client2Api('/resources/accessTokens/sdk', {
    method: 'POST',
    body: {
      userId: new Date().getTime().toString(), // Unique user ID
      levelName, // Verification level
      sumsubIdShareToken,
    },
  });
}

This SDK Access token is used to initialize and launch the WebSDK2.

Examples

Basic Integration

Here's a simplified example of integrating the Sumsub ID Connect button:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Sumsub ID Connect Example</title>
  <style>
    .sumsub-button {
      background-color: #4285f4;
      color: white;
      padding: 10px 20px;
      border-radius: 4px;
      border: none;
      cursor: pointer;
    }
    .sumsub-button:hover { background-color: #3367d6; }
    .sumsub-button:disabled { background-color: #cccccc; }
  </style>
</head>
<body>
  <div id="button-container"></div>

  <script type="module">
    import { createButton } from '@sumsub/id-connect';

    createButton({
      clientId: 'your-client-id',
      container: document.getElementById('button-container'),
      className: 'sumsub-button',
      text: 'Sign in with Sumsub ID',
      onSuccess: (response) => console.log('Authorization successful:', response),
      onError: (error) => console.error('Authorization error:', error.message)
    });
  </script>
</body>
</html>

Changelog

See the CHANGELOG.md file for details on all changes to the library.

License

This package is MIT licensed.

Browser Compatibility

The library is compatible with all modern web browsers (Chrome, Firefox, Safari, Edge, Opera) but has not been tested in native mobile applications.

Support

If you encounter any issues or have questions about this package, please contact Sumsub support.