Sumsub ID supports OpenID Connect (OIDC) — a technical integration layer that lets services connect to a user’s Sumsub ID account through an OpenID Connect-based flow.

The Sumsub ID — OIDC flow supports integrations such as Reusable KYC — Gateway and Sumsub ID Connect. Depending on the integration, businesses can use this flow to request verified identity claims from a user’s Sumsub ID account or to obtain permission to generate Sumsub ID share tokens.

Implementation details

• Issuer: https://id.sumsub.com/
• Configuration URL: https://id.sumsub.com/.well-known/openid-configuration

The OpenID Connect discovery protocol allows you to automatically configure OIDC integrations using the metadata provided at the configuration URL.

Configuration metadata

The configuration contains metadata describing:

• Authorization and token endpoints.
• Userinfo endpoint.
• Supported scopes, response types, and grant types.
• Public keys for ID token validation.

Supported scopes

The following table describes the supported scope values — permissions that grant access to specific actions within Sumsub ID — OIDC flow — used in the following request.

If you include the offline_access scope, Sumsub creates an ongoing connection between the user’s Sumsub ID and your service. This connection allows your service to request verified claims again in the future for any scopes the user has already approved, without asking the user to repeat the full flow. The user creates this connection once and can revoke it at any time from their Sumsub ID account.

Enable OIDC integration

To enable and use OpenID Connect, complete the following steps in the Dashboard:

1. Navigate to Dev Space → OIDC Settings.
2. Generate a secret key and register a redirect URL.
3. Save changes.

Verify with Sumsub ID button

Use the Sumsub ID Connect JavaScript library to add a Verify with Sumsub ID button and run the authorization flow with OIDC.

The library includes:

• Secure OAuth 2.0 authentication with Sumsub ID and customizable button
• Simple API with TypeScript support
• Responsive behavior across devices
• Automatic handling of the authorization flow (including PKCE – Proof Key for Code Exchange)

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

npm install @sumsub/id-connect

yarn add @sumsub/id-connect

pnpm add @sumsub/id-connect

How JavaScript library works

🚧

Attention

• The authorization code expires quickly, so exchange it for tokens as soon as possible.
• Add your domain in the Sumsub ID Connect configuration section.

How to integrate JavaScript library

You can integrate the library in two ways:

1. Use the pre-built button.
   TypeScript

   import { createButton } from '@sumsub/id-connect';
   createButton({
     clientId: 'your-client-id',
     permissions: ['share'],
     loginHint: '[email protected]', // optional: prefills email field
     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: 'Verify with Sumsub ID'
   });

2. Use your own button with the modal.
   TypeScript

   import { openModal } from '@sumsub/id-connect';
   document.getElementById('your-custom-button')!.addEventListener('click', () => {
     openModal({
       clientId: 'your-client-id',
       permissions: ['share'],
       loginHint: '[email protected]', // optional: prefills email field
       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 include the UMD build (JavaScript bundle formatted using the Universal Module Definition pattern) 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'],
    loginHint: '[email protected]', // optional: prefills email field
    container: document.getElementById('button-container'),
    onSuccess: (response) => console.log('Authorization successful:', response.code),
    onError: (error) => console.error('Authorization error:', error.message)
    // The button handles loading state internally
  });
</script>

OIDC Authorization flow

You can use the standard OIDC Authorization flow instead of the JavaScript library.

To do this, use https://id.sumsub.com/snsId/oauth/authorize as a configuration URL.

In the table below, you can find the full list of parameters with its description.

OAuth authorization flow parameters

Here, you can find all parameters you pass to openModal and createButton when you start the OAuth authorization flow with Sumsub ID.

openModal(options)

Call openModal to open a popup window and start the OAuth authorization flow with Sumsub ID.

In the table below, you can find the full list of parameters with its description.

Function behavior

openModal does not return a value. It opens a popup window, starts the OAuth authorization flow with Sumsub ID, and reports the result through the provided 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
});

createButton(options)

Call createButton to render a button that starts the OAuth authorization flow when the user clicks it.

In the table below, you can find the full list of parameters with its description.

Function behavior

createButton does not return a value. It creates a button inside the specified container, wires it to the OAuth authorization flow with Sumsub ID, and reports the result through the provided callbacks

Example:

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',
  text: 'Verify with Sumsub ID'
  // The button manages loading state internally and can call onLoading if provided
});

Types

AuthorizeResponse describes the object that the library passes to onSuccess after a successful authorization.

Example:

type AuthorizeResponse = {
  code?: string;   // Authorization code to exchange for tokens on your backend
  state?: string;  // State value returned from the authorization response
};