Connect Sumsub with your own keys

Before you start

• A Sumsub account with an app token and secret key (Sumsub dashboard → Developers → App tokens).
• Token permissions to create and view applicants.
• A verification level already created in the Sumsub dashboard. Open Dram does not create levels.
• The exact level name. It is case-sensitive, and one level is used for every new user.

This page never creates users and never uploads documents. It only stores a connection that the New user form can use.

• Full Sumsub setup walkthrough (blog) →

Connect

1. Open Settings → Integrations · Sumsub and choose Connect Sumsub. With no connection, the page says users can still be created with Manual KYC.
2. Choose Sandbox or Production. Sandbox tokens start with sbx:, production tokens with prd:. A token from the other environment is refused.
3. Paste the app token and the secret key.
4. Enter the level name exactly as it appears in Sumsub.
5. Leave “Make Sumsub the default for new users” on if new users should get a link automatically.
6. Choose Test and connect.

sequenceDiagram
  actor Staff
  participant UI as Settings · Sumsub
  participant Vault as OS keychain
  participant API as Sumsub API
  participant Led as kyc/events.jsonl
  Staff->>UI: Connect Sumsub
  UI->>UI: environment, app token, secret, level name
  Staff->>UI: Test and connect
  UI->>API: signed request (token check)
  alt 401
    API-->>UI: reject
    UI-->>Staff: Token rejected
  else ok
    API-->>UI: accepted
    UI->>Vault: encrypt token and secret
    UI->>Led: provider.connected
    UI-->>Staff: Connected. Default method can be Sumsub
  end

If you never connect Sumsub, the default method cannot be Sumsub. New users then use Manual KYC or no KYC.

What Test checks

Open Dram sends one signed request that looks up an applicant that cannot exist. A “not found” answer proves the token and signature were accepted. An authentication error means the keys are wrong. Nothing is created in your Sumsub account.

After connecting

• An environment badge (Sandbox or Production).
• The masked token, for example sbx:uY1…****.
• The level name.
• The last test result and time.
• Test, Rotate keys and Disconnect.

There is one Sumsub connection per vault. Sandbox and production are one switch, not two cards; switching environment means entering the other environment's keys with Rotate keys.

Where the keys live

• Keys are encrypted with the operating system keychain (Keychain on macOS, DPAPI on Windows) on the computer that connected.
• They are never written to the vault folder, the ledger, exports or the audit log. The ledger only records a pointer (secret_ref).
• If the vault is opened on another computer, Settings says the keys are not on this computer. Use Rotate keys to enter them there.
• If a computer has no system keychain, Open Dram refuses to store Sumsub keys at all.

Webhook or Fetch status

Sumsub can call a webhook when a review finishes, but only if the app has a public web address. The desktop app does not, so there is no webhook to configure. After the client finishes, open the user and press Fetch status. The result is mapped exactly as a webhook would be.

A hosted install with a public address would subscribe to applicantReviewed (and applicantPending) in Sumsub's webhook manager. Fetch stays available either way.

Rotate and disconnect

• Rotate keys replaces the token and secret after testing the new ones. Existing KYC records keep working.
• Disconnect writes provider.disabled. New users fall back to Manual KYC; existing records and their history are kept.
• After a disconnect, the keys stay encrypted on the computer until you rotate them.

What Settings does not do

• It does not create Sumsub levels — do that in the Sumsub dashboard.
• It does not upload documents.
• It does not make Sumsub the default unless you ask it to. Manual KYC always remains available.