1. Confirm Stage 0a preconditions with the user — one by one. Do not assume any item is done. For each, ask the user whether it exists; if it doesn't, stop and hand them the exact manual step and where to do it (the support email template, the Dev Space → OIDC Settings registration, the App Token minting page, the level creation hand-off). These are Sumsub-dashboard / support actions only — there is no public API for them, so you cannot do them for the user. Wait until every item is confirmed before moving on.
2. Run Stage 0b preflight and require exit 0. Only after the preconditions are confirmed, run

   scripts/preflight.sh

   . Resolve every FAIL (loop back to Stage 0a as needed). Do not proceed on any FAIL.
3. Only now build. With both gates green, proceed to Stage 1 and scaffold the frontend/backend.

• Sumsub support has enabled ID Connect for your workspace. This is not a self-serve toggle — until support flips it, no OIDC client can be created and the preflight will report

  connect_token: ID Connect not enabled for this workspace

  . Email your CSM or

  support@sumsub.com

  first and wait for confirmation. Template:

  ```
  Subject: Enable Sumsub ID Connect for clientId <YOUR_CLIENT_ID> (sandbox)
  
  Hi Sumsub team,
  
  Please enable Sumsub ID Connect for our workspace.
  
    Environment:         sandbox
    clientId:            <YOUR_CLIENT_ID>          (Dashboard top-left)
    Intended scopes:     openid, share, name        (adjust as needed)
    Intended recipients: self                       (or list partner clientIds)
    Use case:            <one-line description of where the button will live>
  
  Once enabled we'll register the OIDC client + redirect URIs in
  Dev Space → OIDC Settings.
  
  Thanks
  ```

• App Token + secret (sandbox). Minted at https://cockpit.sumsub.com/checkus/devSpace/appTokens with workspace toggled to Sandbox. Both values shown once at creation. → exported as

  SUMSUB_APP_TOKEN

  /

  SUMSUB_SECRET_KEY

  .
• OIDC client registered at Dashboard → Dev Space → OIDC Settings. Capture all three: -

  client_id

  (public — goes in the browser, used as

  forClientId

  for the share token in the common self-recipient case) -

  client_secret

  (shown ONCE at creation; if you lose it you must regenerate, which invalidates existing integrations). Required for the Stage 2 code→token exchange — keep it server-side only. -

  redirect_uri

  allowlist populated for BOTH callbacks (Sumsub matches byte-for-byte — trailing slash, casing, port, query all matter): - your authorize callback (e.g.

  https://yourapp.com/auth/callback

  ) - your shareLink callback (e.g.

  https://yourapp.com/share-complete

  ) Sumsub redirects the browser back to these URLs and requires public HTTPS — a bare

  http://localhost:3000

  won't work for local testing. To develop on your machine, expose your local server with a public HTTPS tunnel (ngrok) and allowlist that origin — see Local development with ngrok below.
• At least one verification level exists in this workspace. Capture

  levelName

  . If none, hand off to

  sumsub-create-level

  first — Stage 4 can't materialise an applicant without one.
• At least one Sumsub ID account with verified data for end-to-end testing. An email-only account (no completed KYC) makes Stage 4 fail with errorCode

  10521 reusable-kyc-inactive-sumsub-id-account

  — see the error table at the end of Stage 4.

http://localhost

redirect_uri

redirect_uri

localhost

1. Start your backend locally (the example listens on

   PORT=3000

   ):
   bash

   PORT=3000 node examples/express-callback.js

2. Open a tunnel to that port. Prefer a reserved (static) domain so the URL survives restarts — a free random ngrok URL changes on every launch and forces you to re-edit the allowlist each time:
   bash

   ngrok http 3000 --domain=your-reserved-name.ngrok-free.app
   # or, ephemeral URL (changes each restart): ngrok http 3000

   ngrok prints a forwarding URL, e.g.

   https://your-reserved-name.ngrok-free.app

   .
3. Allowlist BOTH callbacks at the ngrok origin in Dashboard → Dev Space → OIDC Settings (sandbox workspace) — byte-for-byte, including trailing slash:

   https://your-reserved-name.ngrok-free.app/
   https://your-reserved-name.ngrok-free.app/share-complete

4. Point the app at the public URL, not localhost. The browser's

   redirect_uri

   and the server-side shareLink

   redirectUri

   must derive from the same public origin, so set

   PUBLIC_BASE_URL

   and restart:
   bash

   PUBLIC_BASE_URL=https://your-reserved-name.ngrok-free.app \
     PORT=3000 node examples/express-callback.js

   Then open the ngrok URL (not

   localhost:3000

   ) in the browser so the

   redirect_uri

   it sends matches the allowlist.

⚠️ Re-register on every URL change. If you use an ephemeral ngrok URL, the allowlist entry (and

PUBLIC_BASE_URL

) must be updated each time ngrok restarts. A reserved domain avoids this churn.

ngrok's free interstitial ("You are about to visit…") only affects API/XHR calls, not top-level browser navigation, so it doesn't block the OIDC redirects. A reserved domain or paid plan removes it entirely.

⛔ Gate. Do not start this stage until Stage 0a preconditions are all confirmed with the user AND Stage 0b preflight exits 0. If you haven't done both, go back — see "Order of operations" above. This is the first stage where you write code; everything before it is setup you must verify first.

id.sumsub.com

api.sumsub.com

@sumsub/id-connect

• Frontend (this stage) — page with the button. Generates PKCE, kicks off the OIDC redirect to

  id.sumsub.com

  , receives

  ?code=

  in the callback, POSTs

  { code, codeVerifier }

  to your own backend.
• Backend (Stages 2-4) — HTTP endpoint that your frontend POSTs to. Signs Sumsub API calls with your App Token + secret (which must NEVER reach the browser), orchestrates the chain

  code → access_token → share token → reuse

  , and returns the materialised applicant.

POST /api/sumsub/id-connect/exchange

examples/oidc-button.html

examples/express-callback.js

⚠️

onSuccess

is not a verification signal. It only confirms the user finished the OIDC consent step and Sumsub issued an authorization code. The actual verification verdict comes from Stage 4 —

applicant.review.reviewStatus

in the

/reuse

response (immediate, if your recipient level runs no additional checks) or the

applicantReviewed

webhook (authoritative, for any level that runs post-reuse checks). Never grant access or unlock features based on

onSuccess

firing.

createButton

client_secret

client_secret_basic

POST https://id.sumsub.com/api/snsId/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(<client_id>:<client_secret>)

grant_type=authorization_code
&code=<the code your frontend got>
&redirect_uri=<exact-match URI from Stage 1 — byte-for-byte>
&code_verifier=<PKCE verifier matched to the code_challenge from Stage 1>

access_token

{
  "access_token":  "snd-id-con-a-...",
  "refresh_token": "snd-id-con-r-...",   // only with `offline_access`
  "token_type":    "Bearer",
  "expires_in":    86400,
  "id_token":      "eyJhbGc..."           // only with `openid` — RS256-signed
}

grant_type: "refresh_token"

The

client_secret

stays server-side — never in the browser bundle. The exchange is

client_secret_basic

/

client_secret_post

; do not HMAC-sign it. (The App-Token + HMAC auth is still used in Stage 3a/4 for the share token and reuse calls.)

• Invalid code

  401 has three common causes: PKCE mismatch (verifier doesn't hash to the challenge sent at authorize), code already used (single-use; refreshing the callback page double-fires), or code expired (short TTL — exchange immediately).

• redirect_uri

  must match Stage 1 byte-for-byte — trailing slash, casing, port and query all count, or the exchange fails.

• id_token

  validation — use a mature library (

  jose

  ,

  pyjwt

  ,

  jjwt

  ) against the

  jwks_uri

  from

  .well-known/openid-configuration

  . Never trust unverified JWT contents.

POST https://api.sumsub.com/resources/accessTokens/sumsubIdShareToken
{
  "sumsubIdConnectToken": "<access_token from Stage 2>",
  "forClientId":          "<recipient clientId>",
  "ttlInSecs":            1800
}

forClientId

• Self-recipient (common case): your own workspace

  clientId

  , visible in the Dashboard top-left.
• Third-party recipient: the partner's

  clientId

  (they must be pre-registered as a partner in the Dashboard).

{
  "token":          "_act-snsId-...",
  "forClientId":    "<echoed>",
  "sharingAllowed": true    // or false → continue to Stage 3b
}

sharingAllowed: false

POST https://api.sumsub.com/resources/snsId/oauth/shareLink
Authorization: Bearer <access_token from Stage 2>
X-App-Token + X-App-Access-Ts + X-App-Access-Sig

{
  "redirectUri": "<your shareLink callback URL — must be in the allowlist>",
  "forClientId": "<same recipient clientId>",
  "displayMode": "page",
  "state":       "<csrf-or-correlation-id>"
}

{ "link": "https://id.sumsub.com/share/<id>" }

access_token

state

link

redirectUri

?token=<JWT>

state

sharingAllowed: true

forClientId

⚠️

state

is inside the JWT payload, not a top-level

?state=

query param. Decode the

token

JWT to read

state

back (verify its signature against the

jwks_uri

first), then look up the saved

access_token

by that

state

. Re-call Stage 3a — the share token now returns

sharingAllowed: true

. Decoded payload shape:

{ iss, sub, aud, iat, exp, sharingAllowed, state, forClientId }

.

examples/express-callback.js

pendingShare

state

/share-complete

• Sumsub support has enabled Sumsub ID Connect for the production

  clientId

  (separate from sandbox).
• Production

  redirectUri

  s (both authorize and shareLink callbacks) are in the Dashboard allowlist on the prod workspace.
• Backend token-exchange endpoint is auth-gated (only the authenticated user can exchange a code minted for them).

• id_token

  signature is verified against the prod JWKS.

• externalUserId

  is stable per real user (not email, not display name).

• /reuse/preview

  is called before

  /reuse

  so compatibility errors surface as UX, not 4xx noise.
• Stage 3b shareLink flow is implemented and tested — don't ship code that only handles

  sharingAllowed: true

  .
• In-memory state used for the shareLink callback is replaced with a real session store (Redis / encrypted cookie / DB).
• App Token + secret + OIDC

  client_secret

  are in the prod secret store, not committed and not in browser bundles.
• Refresh-token storage (if used) is server-side only, encrypted at rest, single-tenant.

• references/scopes-and-claims.md

  — full scope table, token-endpoint response shape, error codes.

• scripts/preflight.sh

  — preconditions validator.

• examples/oidc-button.html

  — Method 1 (

  createButton

  ) — recommended.

• examples/oidc-modal.html

  — Method 2 (

  openModal

  ).

• examples/oidc-redirect.html

  — Method 3 (raw OIDC redirect with PKCE).

• examples/express-callback.js

  — full backend (Stages 2-4 incl. Stage 3b consent flow).

• sumsub-api-auth

  — auth signing reference.

• sumsub-create-level

  — when the workspace has no recipient level yet.

• sumsub-integrate-websdk

  — sibling skill; reuse its webhook material once the applicant is materialised.