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 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 Connect Refresh token: A long-lived token that allows client1 to get new Sumsub ID Connect token.

• 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 Scenarios

Share Flow

1. Initialization: The library prepares the authorization flow with your client ID and optional security parameters
2. Authorization: A popup window opens where the user authorizes with Sumsub ID
3. Authorization Code: Upon success, your app receives an authorization code via the onSuccess callback
4. Token Exchange: Your backend exchanges this code for Sumsub ID Connect tokens (see Getting a Sumsub ID Connect Token)
5. Share: Your backend creates Sumsub ID Share Token (see Getting a Sumsub ID Share Token) For security reasons, all token exchange operations should be performed on your backend, never in the browser.

OIDC Flow

1. Initialization: The library prepares the authorization flow with your client ID and optional security parameters
2. Authorization: A popup window opens where the user authorizes with Sumsub ID
3. Authorization Code: Upon success, your app receives an authorization code via the onSuccess callback
4. Token Exchange: Your backend exchanges this code for tokens
5. Using the Tokens: Your backend uses Sumsub ID Connect token to get user details For OIDC authentication flow use token and userinfo endpoints, described in the OIDC metadata file: https://id.sumsub.com/.well-known/openid-configuration Provide secret key defined in Sumsub ID Connect configuration section.

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. Important: Add your domain in Sumsub ID Connect configuration section.

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', 
  permissions: ['share'],  
  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',
    permissions: ['share'],
    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',
    permissions: ['share'],
    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
• permissions (string[]): Requested permissions (scopes) : e.g., ['openid', 'share', 'offline_access', 'email', 'name']
• 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
• loginHint (string, optional): Email address to pre-fill on the Sumsub ID login screen (button-flow equivalent of the OIDC login_hint parameter)
• 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', 
  permissions: ['share'],
  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
  loginHint: '[email protected]' // Optional: pre-fills the email on the login screen
});

createButton(options)

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

Parameters

• options (Object):
  • clientId (string): Your Sumsub ID client id
  • permissions (string[]): Requested permissions (scopes) : e.g., ['openid', 'share', 'offline_access', 'email', 'name']
  • 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
  • loginHint (string, optional): Email address to pre-fill on the Sumsub ID login screen (button-flow equivalent of the OIDC login_hint parameter)
  • 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',
  permissions: ['share'],  
  scope: 'space separated scopes',
  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
});

Supported permissions

• openid Returns the ID token (id_token). Required by OpenID Connect (OIDC).
• profile Grants access to the user’s basic profile information.
• email Grants access to the user’s email address.
• name Grants access to the user’s name information.
• share Grants permission to generate a Sumsub ID Share token.
• offline_access Grants permission to obtain a Refresh token.

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:

1. Have a client-key (client ID) enabled for Sumsub ID Connect
2. 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 API Reference
Method: POST
Request Body:

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

Response: { "access_token": "sumsub_id_connect_token_value" , "refresh_token": "sumsub_id_connect_refresh_token_value" }

Example (cURL):

curl -X POST https://api.sumsub.com/resources/snsId/api/connect/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "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 API Reference 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.