End-to-end recipe for integrating Sumsub ID Connect — the OIDC-based "Verify with Sumsub ID" flow that lets a user share previously-verified identity claims with your app. TRIGGER when the user asks to "integrate Sumsub ID Connect", "add Verify-with-Sumsub-ID button", "reuse Sumsub KYC via OIDC", "e

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 ](../sumsub api auth/SKILL.md). ⛔ 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 ](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 Endpoints METHOD URL Auth Stage (browser redirect) https://id.sumsub.com/api/snsId/oauth/authorize none 1 GET https://id.sumsub.com/.well known/openid configuration none 0b GET https://id.sumsub.com/.well known/jwks.json none (id token validation) POST https://id.sumsub.com/api/snsId/oauth/token client secret basic 2 POST https://api.sumsub.com/resources/accessTokens/sumsubIdShareToken App Token + HMAC 3a POST https://api.sumsub.com/resources/snsId/oauth/shareLink App Token + HMAC + Bearer 3b GET https://api.sumsub.com/resources/api/reusableIdentity/reuse/preview App Token + HMAC 4 POST https://api.sumsub.com/resources/api/reusableIdentity/reuse App Token + HMAC 4 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: [ ] 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]( local development with ngrok) below. [ ] At least one verification level exists in this workspace. Capture levelName . If none, hand off to [ sumsub create level ](../sumsub create level/SKILL.md) 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. Stage 0b — Preflight [ scripts/preflight.sh ](scripts/preflight.sh) machine validates the preconditions that can be probed without minting OIDC codes or creating applicants. It does not mutate anything. Checks (each independent — one failing doesn't abort the others): Check What it proves connect token App Token HMAC signing is accepted and ID Connect is enabled for the workspace — probes the endpoint with a known bad code and expects 401 Invalid code (a 404 invalid clientId means ID Connect isn't enabled). This is a connectivity/entitlement probe, not the Stage 2 exchange route. oidc discovery https://id.sumsub.com/.well known/openid configuration returns a valid OIDC discovery doc levels At least one verification level exists in this workspace Exit code: 0 on all PASS / PASS+WARN, 10 on any FAIL. Resolve all FAILs before Stage 1. Local development with ngrok ID Connect can't be tested against http://localhost . Sumsub redirects the browser back to your redirect uri after the authorize flow (Stage 1) and after the shareLink consent flow (Stage 3b), and it requires the URL to be public HTTPS and present in the OIDC client's redirect uri allowlist byte for byte . A bare localhost URL is neither public nor HTTPS, so the redirect fails. For local development, put a public HTTPS tunnel in front of your local server with [ngrok](https://ngrok.com/) and allowlist that origin. 1. Start your backend locally (the example listens on PORT=3000 ): 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: 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: 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: 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. Stage 1 — Frontend: the button ⛔ 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. Architecture — what's yours vs Sumsub's Sumsub provides: the OIDC service ( id.sumsub.com ), the HMAC API ( api.sumsub.com ), and the optional @sumsub/id connect JS library that mounts the button. You write both halves of the integration: 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. The two halves are coupled by one route name — POST /api/sumsub/id connect/exchange in the examples; rename to fit your routing. Reference pair (matched): [ examples/oidc button.html ](examples/oidc button.html) (frontend) + [ examples/express callback.js ](examples/express callback.js) (backend). The backend is a thin orchestrator (~180 lines of Node/Express); port it to your stack of choice — the wire format is identical regardless of language. ⚠️ 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. Three variants — use Method 1 ( createButton ) by default; the others exist for design system or no bundler scenarios. Method 1 — pre built button via @sumsub/id connect (recommended) Why generate PKCE yourself: the Stage 2 token exchange needs the verifier . If you let the library generate it, you depend on the library's internal sessionStorage key (undocumented per minor version) to read it back in onSuccess . Passing your own codeChallenge keeps the verifier under a key you own. Same pattern works for Methods 2 and 3. Runnable example: [ examples/oidc button.html ](examples/oidc button.html). Method 2 — your trigger + library modal Same library, you own the trigger element; library opens the flow in an overlay via openModal({...}) . Use when your design system has its own buttons. Runnable example: [ examples/oidc modal.html ](e

sumsub-integrate-id-connect