Sumsub Integrate ID Connect

Sumsub — ID Connect integration

Embed the "Verify with Sumsub ID" OIDC flow end-to-end — preconditions → preflight → button → backend exchange → consent → applicant in your workspace.

⚠️ Sandbox tokens only

Do not use a production App Token / secret while wiring this up. Insist on a sandbox pair from <https://cockpit.sumsub.com/checkus/home?sbx=true> — Connect Sumsub to your AI agent -> Build & configure -> Generate token. Token + secret are revealed once at creation; copy both before closing the dialog. The preflight enforces this with an sbx: prefix check.

Deeper auth mechanics: `sumsub-api-auth`.

⛔ Order of operations — do NOT scaffold an app first

This is the single most important rule of this skill. Write no frontend or backend code, create no demo project, scaffold nothing until BOTH gates below are green. The client-side Sumsub setup (Stage 0a) is manual and cannot be done by you — jumping to code before it exists produces an app that can't authenticate, can't redirect, and can't reuse. Always follow this sequence:

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.

If the user says "just build the demo" before the gates are green, briefly explain why it won't work yet and walk them through the missing precondition first. The code is the last step, not the first.

What ID Connect is (and isn't)

Sumsub ID Connect lets a business request specific verified identity claims — age, name, nationality, email, country of residence, humanness — from a Sumsub ID account belonging to the end-user. Sumsub hosts the entire user-facing flow: sign-in, account creation (if needed), email OTP, any missing verification steps, and a per-recipient consent screen. Your app receives the result as a signed OIDC token plus, optionally, an applicant materialised in your workspace through Reusable KYC.

This is not the WebSDK. The WebSDK runs a full KYC capture inside your page; ID Connect delegates the whole UX to Sumsub.

The lifecycle in one picture

 ┌──────────────────────────────┐
 │ Stage 0a Preconditions check │  manual setup on Sumsub side
 │ Stage 0b scripts/preflight.sh │  automated validation
 └──────────────┬───────────────┘
                │ clientId, levelName, allowlist
 ┌──────────────▼───────────────┐
 │ Stage 1: Frontend "Verify…"  │  authorize redirect with PKCE
 │   button                      │
 └──────────────┬───────────────┘
                │ onSuccess({ code, state })
 ┌──────────────▼───────────────┐
 │ Stage 2: code → access_token  │  POST id.sumsub.com/api/snsId/oauth/token
 │   (client_secret_basic)       │
 └──────────────┬───────────────┘
                │ access_token
 ┌──────────────▼───────────────┐
 │ Stage 3a: → share token       │  POST /resources/accessTokens/sumsubIdShareToken
 └──────────────┬───────────────┘
                │ sharingAllowed?
        ┌───────┴────────┐
        │ false           │
        ▼                ▼ true
 ┌──────────────────┐ ┌──────────────────────────────┐
 │ Stage 3b:        │ │ Stage 4: reuse/preview +     │
 │ shareLink        │ │   reuse/commit               │
 │ redirect + retry │ │ → applicant in your workspace │
 └────────┬─────────┘ └──────────────────────────────┘
          │
          └──────► back to Stage 3a (retry — now sharingAllowed: true)

Endpoints

The "Enable Sumsub ID Connect" toggle, OIDC client registration (client_secret + redirect_uri allowlist), and sharing-partner registration are Sumsub dashboard UI only — no public-API equivalent.

Stage 0a — Preconditions checklist

Before any code or preflight, the following must already exist on the Sumsub side. Each item maps to a check below or to a runtime failure if missed.

• [ ] 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/home?sbx=true> via Connect Sumsub to your AI agent -> Build & configure -> Generate token. 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