sumsub/agent-skills / skills/sumsub-integrate-dint-standalone
sumsub-integrate-dint-standalone
VerifiedAdd Sumsub Device Intelligence (the Fisherman JS module) to your own web pages where there is NO Sumsub verification widget — login, signup, password reset, 2FA, checkout, or any high-value action you want fraud-screened. TRIGGER when the user asks to "add device intelligence to login / signup", "fingerprint the device on a custom page", "use Fisherman standalone / self-hosted", "ongoing monitoring of platform events", "pre-KYC device check", "detect multi-accounting at signup", or "send a financial transaction with the captured device". Covers the whole loop — behavior access token, @sumsub/fisherman init + fingerprint, confirming the event (platform event / financial transaction / create-applicant), reading results, sandbox, go-live. SKIP when the page already embeds the Sumsub WebSDK — Device Intelligence rides along inside it, use `sumsub-integrate-dint-websdk`.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.8 KB |
| SKILL.md | skill md | 16.6 KB |
| examples/behavior-token.sh | script | 2.1 KB |
| examples/fisherman-react.tsx | other | 2.6 KB |
| examples/fisherman-vanilla.html | other | 2.4 KB |
| examples/submit-platform-event.sh | script | 3.7 KB |
| references/standalone-flow.md | markdown | 3.9 KB |
| scripts/preflight.shexecutable | script | 7.0 KB |
SKILL.md
View on GitHub---
name: sumsub-integrate-dint-standalone
description: >-
Add Sumsub Device Intelligence (the Fisherman JS module) to your own web
pages where there is NO Sumsub verification widget — login, signup, password
reset, 2FA, checkout, or any high-value action you want fraud-screened.
TRIGGER when the user asks to "add device intelligence to login / signup",
"fingerprint the device on a custom page", "use Fisherman standalone /
self-hosted", "ongoing monitoring of platform events", "pre-KYC device
check", "detect multi-accounting at signup", or "send a financial transaction
with the captured device". Covers the whole loop — behavior access token,
@sumsub/fisherman init + fingerprint, confirming the event (platform event /
financial transaction / create-applicant), reading results, sandbox, go-live.
SKIP when the page already embeds the Sumsub WebSDK — Device Intelligence
rides along inside it, use `sumsub-integrate-dint-websdk`.
allowed-tools: Read, Write, Bash
---
# Sumsub — Device Intelligence standalone (no WebSDK)
Run **Device Intelligence (DI)** on your own pages that have no Sumsub
verification widget — logins, signups, password resets, 2FA, checkouts. You
embed the **Fisherman** JS module (npm `@sumsub/fisherman`) directly, capture
the device on a user action, and confirm the action to Sumsub so it can screen
for device fraud (bots, emulators, VPN/proxy, reused devices, multi-accounting).
This is Sumsub's **ongoing-monitoring / pre-KYC** path. If your page already
shows the Sumsub WebSDK, stop — DI is built into it, use
[`sumsub-integrate-dint-websdk`](../sumsub-integrate-dint-websdk/SKILL.md) instead.
## ⚠️ Sandbox tokens only
Do **not** accept or use a production App Token / secret during integration
work. 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 curl recipes here assume an
`sbx:` token; the preflight enforces it with an `sbx:` prefix check. Deeper auth
mechanics: [`sumsub-api-auth`](../sumsub-api-auth/SKILL.md).
## Before you start — fit DI into the existing app
DI should look like it was always part of their codebase — their framework, their
components, their styling, their conventions. **Don't scaffold over someone's app**
or introduce a new design system. Read enough of the repo to match it, then ask only
what you can't infer:
- **Which action to screen?** The high-value submit to hook DI onto — login,
signup, withdrawal, checkout, 2FA, password reset. (Show the ones you found in
their routes/components as suggestions.)
- **Where's the backend?** The server file/route that can mint the behavior token
and sign the Stage-3 confirm — HMAC **must** stay server-side. If they're
frontend-only (SPA, no backend), flag that they need a server endpoint and offer
to add a minimal one in their stack.
- **Existing Sumsub footprint?** Do they already call Sumsub / have App Token +
secret wired, an `externalUserId` convention, a webhook receiver? Reuse it; don't
duplicate.
- **How are secrets / env handled?** Match their existing pattern (`.env`, secrets
manager, config service) for `SUMSUB_APP_TOKEN` / `SUMSUB_SECRET_KEY` — sandbox
values only during integration.
- **TypeScript or JS?** Match the repo; don't add TS to a JS project or vice-versa.
Map the chosen action to its Stage-3 confirm event:
| Action | Stage-3 confirm event |
|---|---|
| Login / signup / password reset / 2FA | platform event |
| Money movement (transfer, withdrawal, deposit, payment) | platform event + financial txn |
| Pre-KYC signup where you also create the applicant | pre-KYC create-applicant |
| Guest / high-value checkout | financial txn |
Start with **Stage 0 (preflight)** to confirm the workspace has the DI entitlement
before writing any code. Then implement Stages 1–4 against *their* files: a token
route in their backend style, `fisherman.fingerprint()` on their existing submit
handler (fail-open), the server-side confirm with the event mapped from the chosen
action. Touch the minimum needed; follow surrounding code style.
## The loop in one picture
```
┌─────────────────────────────┐ ┌──────────────────────────────────────┐
│ 1. Browser hits your page │─▶│ Your backend: POST .../accessTokens/ │
│ (login / signup form) │ │ behavior {sessionId} → {token} │
└─────────────┬───────────────┘ └──────────────────────────────────────┘
│ behavior access token
┌─────────────▼───────────────┐
│ 2. Browser: @sumsub/fisherman│ ← init(token) → fingerprint() on submit
│ captures the device │ returns { visitorId }
└─────────────┬───────────────┘
│ user submits (login succeeds / account created)
┌─────────────▼───────────────┐ ┌──────────────────────────────────────┐
│ 3. Your backend confirms the │─▶│ Sumsub runs DI analysis on the event │
│ event w/ captured device │ │ (platform event / txn / applicant) │
└─────────────┬───────────────┘ └──────────────────────────────────────┘
│ verdict + device signals
┌─────────────▼───────────────┐ ← Dashboard → Transactions (User
│ 4. You read results / act │ platform event); or webhook
└──────────────────────────────┘
```
The headline: capturing the device is inert until you **confirm the event
server-side** (Stage 3). Capturing alone produces no verdict — the confirm call
is what makes Sumsub run the analysis.
## Vocabulary (get these right — they're load-bearing)
| Term | What it is | Who sets it |
|---|---|---|
| `sessionId` | **The correlation key.** Ties every fingerprint + event in one DI session together, and is the session the behavior token is minted with — so the Stage-3 confirm correlates the captured device to the event server-side, with no device fields in the body. | **Your backend** — generate one per logical session, opaque & unique. |
| `deviceBindingId` | Optional alternative linking id. Sumsub is migrating device linking from `sessionId` to `deviceBindingId`; on the default flow it is **not** required. If you use it: pass it to `fingerprint()`, mint the token with it, and send it at `applicant.device.deviceBindingId` in the confirm body. | **Your frontend** — a fresh `crypto.randomUUID()` per action. |
| `linkedId` | Optional — links the fingerprint to an entity (your user id / applicant id). | Frontend (optional). |
| `visitorId` | The device identifier `fingerprint()` returns; surfaces in results. On the standalone confirm flow you do **not** forward it — the token's session ties the capture to the event. | Returned by Fisherman. |
## Stage 0 — Preflight
[`scripts/preflight.sh`](scripts/preflight.sh) machine-validates the workspace
before you write any frontend code:
```bash
SUMSUB_APP_TOKEN=sbx:... SUMSUB_SECRET_KEY=... \
bash scripts/preflight.sh
```
| Check | What it proves |
|---|---|
| `behavior_token` | HMAC signing is accepted **and Device Intelligence is enabled** for this workspace — mints a real short-TTL behavior token (discarded, expires on its own; nothing else is mutated) |
| `levels` | Verification levels exist. **WARN-only** — just the pre-KYC confirm path (create-applicant) needs one; platform events work without it |
Exit code: `0` on all-PASS / PASS+WARN, `10` on any FAIL. A `403` on
`behavior_token` usually means the **DI entitlement is off** for the
workspace — it's not self-serve; ask your CSM or `support@sumsub.com` to
enable Device Intelligence, mentioning your `clientId` (Dashboard top-left)
and environment (sandbox/production). Resolve all FAILs before Stage 1.
## Stage 1 — Backend: mint a behavior access token
Separate endpoint from the WebSDK token — note the `/behavior` suffix and the
JSON body:
```
POST https://api.sumsub.com/resources/accessTokens/behavior
Content-Type: application/json
{ "sessionId": "<your-session-id>", "ttlInSecs": 1800 }
```
- Auth: App Token + HMAC. **The body is part of the signature** — sign
`ts + "POST" + path + body` (the empty-body shortcut from the WebSDK skill
does not apply here). See [`examples/behavior-token.sh`](examples/behavior-token.sh).
- Response: `{ "token": "_act-jwt-..." }` — the JWT is the `token` field, **not**
`accessToken`. (Behavior tokens carry no `userId`, unlike the WebSDK access-token endpoint.)
- TTL defaults to 1800s. Mint on demand per session; don't cache globally.
Wire it as an auth-gated route on your backend (e.g. `POST /api/di/token`) that
generates/looks up the `sessionId`, signs, calls Sumsub, and returns the response
`token` to the browser.
## Stage 2 — Frontend: capture the device with Fisherman
```bash
npm i @sumsub/fisherman --save
```
```ts
// Shape only — the full impl (fail-open try/catch, React StrictMode teardown) is in
// examples/fisherman-vanilla.html and examples/fisherman-react.tsx.
import { init, destroy } from '@sumsub/fisherman'
// init once when the page / form mounts — getBehaviorToken() calls your Stage-1 route
const fisherman = await init({
token: await getBehaviorToken(),
baseUrl: 'https://api.sumsub.com', // region-specific API host
accessTokenUpdateHandler: getBehaviorToken, // refresh near expiry
onError: () => destroy(), // never let DI block your form
})
// on the user action (e.g. login submit) — gate, fresh deviceBindingId, then confirm server-side
if (fisherman?.isDeviceIntelligenceEnabled) {
const deviceBindingId = crypto.randomUUID()
await fisherman.fingerprint({ deviceBindingId /*, linkedId: userId */ })
// Fisherman posts the capture under the token's session — your Stage-3 confirm
// call needs only the same accessToken to tie this device to the event.
}
destroy() // re-init for the next action
```
Rules:
- Gate `fingerprint()` on `isDeviceIntelligenceEnabled` — skip silently if DI is
off for the workspace.
- A **fresh `deviceBindingId` per action**. Correlation of the capture to the
confirm call is the token's `sessionId`, not this id — only the `deviceBindingId`
migration path needs it echoed in the confirm body (Stage 3).
- DI must **never block your real flow** — wrap in try/catch, fail open.
- `destroy()` after the action; re-`init()` for the next one. Refresh tokens via
`accessTokenUpdateHandler` (or call `updateAccessToken(newToken)` manually).
Runnable starting points: [`examples/fisherman-vanilla.html`](examples/fisherman-vanilla.html),
[`examples/fisherman-react.tsx`](examples/fisherman-react.tsx).
## Stage 3 — Backend: confirm the event with the captured device
Tell Sumsub the action happened; the captured device rides along via the token's
session. Pick the call that matches the action — all use your **standard App
Token + HMAC signing** (sign `ts + "POST" + path + body`, exactly like every other
Sumsub API call), and additionally carry the **behavior access token** as the
`?accessToken=` query param so Sumsub ties the captured device to the event. The
`accessToken` does **not** replace signing — it rides alongside it:
| Action | Endpoint | Doc |
|---|---|---|
| Login / signup / password reset / 2FA | `POST /resources/applicants/-/kyt/txns/-/data?accessToken=…` | [platform event](https://docs.sumsub.com/reference/send-applicant-platform-event-with-captured-device) |
| Financial transaction | `POST /resources/applicants/-/kyt/txns/-/data?accessToken=…` | [financial txn](https://docs.sumsub.com/reference/send-financial-transaction-with-captured-device) |
| Pre-KYC signup (create the applicant) | create applicant with `levelName` + `accessToken` + `externalUserId` | [pre-KYC check](https://docs.sumsub.com/reference/use-device-intelligence-for-pre-kyc-check) |
**How the device links:** the confirm call is App-Token + HMAC signed **and**
carries the **same behavior access token** as `?accessToken=`. Sumsub correlates
the captured fingerprint to the event **server-side using the session the token
was minted with** (it reconstructs the key from your `externalUserId`; the token
scopes the session). You do **not** put `visitorId` or a device block in the
body — just identify the user + the event:
```json
{
"txnId": "<unique-id-you-generate>",
"type": "userPlatformEvent",
"applicant": { "externalUserId": "<your-user-id>", "type": "individual" },
"userPlatformEventInfo": { "type": "login" }
}
```
Runnable: [`examples/submit-platform-event.sh`](examples/submit-platform-event.sh).
Financial-transaction and pre-KYC bodies + full field lists:
[`references/standalone-flow.md`](references/standalone-flow.md).
> `deviceBindingId`-based linking (Sumsub is migrating to it) is the exception:
> mint the token with a `deviceBindingId`, pass the same one to `fingerprint()`,
> and send it at `applicant.device.deviceBindingId`. The default flow keys on
> `sessionId` and needs none of that.
For **pre-KYC**, also add `creationTrackingData.ip` to the applicant if
you want Advanced IP verification, then request the applicant check to trigger
the DI analysis.
## Stage 4 — Read the results
- **Dashboard:** Transactions and Travel Rule → **Transactions**, filter by
type **User platform event** → open the row → device details + risk labels.
- **Webhooks:** subscribe to the transaction/event reviewed webhooks to gate
programmatically (same signature-verification rules as the WebSDK skill —
verify on raw bytes).
- Device risk labels + scoring are the same catalog as the WebSDK path:
[`references/standalone-flow.md`](references/standalone-flow.md). Full signal
definitions are in the `sumsub-integrate-dint-websdk` skill's
`references/device-signals.md` (install that skill for the file).
Decide which device labels are blocking (refuse / step-up) vs informational
(log) — that policy is yours.
## Sandbox testing
- Sandbox has no real device signals; Fingerprint is simulated. Use the
`simulationConfig` (`FpSimulationConf`) option on `init` to force specific
signals for deterministic test outcomes.
- Run the full loop in sandbox (token → fingerprint → confirm) and confirm a
**User platform event** transaction appears in the dashboard.
## Going live checklist
- [ ] Backend mints the **behavior** token (`/accessTokens/behavior`), signing
the **body**, with a unique per-session `sessionId`.
- [ ] Token endpoint is auth-gated (only your authenticated context can mint).
- [ ] Frontend fails open — a Fisherman error never blocks login/signup.
- [ ] Unique `sessionId` per session in the behavior token — it's what correlates
the captured device to the confirm call (no device fields needed in the body).
- [ ] You confirm the event server-side (platform event / txn / applicant) so
Sumsub actually runs the analysis — capturing alone produces no verdict.
- [ ] Results read from the dashboard / webhook, not from the browser.
- [ ] Production App Token + secret in the prod store; sandbox values stay in dev.
## See also
- [`sumsub-integrate-dint-websdk`](../sumsub-integrate-dint-websdk/SKILL.md) — DI when
the page already embeds the Sumsub WebSDK widget.
- [`sumsub-integrate-websdk`](../sumsub-integrate-websdk/SKILL.md) — the base
KYC WebSDK embed (token signing, webhook patterns reused here).
- [`sumsub-api-auth`](../sumsub-api-auth/SKILL.md) — HMAC signing shared by every
Sumsub skill.
- [`scripts/preflight.sh`](scripts/preflight.sh) — workspace validator (run
before Stage 1).
- [`references/standalone-flow.md`](references/standalone-flow.md) — concepts,
event types, result reading, pre-KYC and financial-txn variants.
- [Get started with Device Intelligence](https://docs.sumsub.com/reference/get-started-with-device-intelligence),
[Generate access token](https://docs.sumsub.com/reference/generate-access-token-device-intelligence),
[`@sumsub/fisherman`](https://www.npmjs.com/package/@sumsub/fisherman) — authoritative source if this skill drifts.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |