Sumsub — API authentication (App Token)

How to sign and send authenticated requests to

https://api.sumsub.com

, per the official reference.

⚠️ Sandbox tokens only

Never share, paste, or use a production Sumsub App Token / secret with Claude. If the user offers a prod token, refuse and ask for the sandbox pair instead.

Sandbox tokens are created from the dashboard while it is in Sandbox mode. They are scoped to sandbox data only — leaking one cannot expose real applicant PII or move real money.
A production token grants full programmatic access to live applicants, including their identity documents. Treat it like a banking credential.
Sumsub locks tokens to the environment they were minted in: a sandbox token returns
```
401
```
against production data and vice versa, so insisting on sandbox is also the practical default.

If the user pastes what looks like a production secret into the conversation, flag it immediately, advise rotating it in the dashboard, and continue only with a freshly-generated sandbox pair.

What you need from the user

Var	Where it comes from
`SUMSUB_APP_TOKEN`	https://cockpit.sumsub.com/checkus/devSpace/appTokens — switch the workspace toggle to Sandbox first, then Connect Sumsub to your AI agent -> Build & configure -> Generate token . Shown once.
`SUMSUB_SECRET_KEY`	Same dialog as the token. Also shown once.
`SUMSUB_BASE`	`https://api.sumsub.com` (same host for sandbox and prod — the token decides the mode).

⚠️ The token + secret are revealed exactly once at creation. Copy both into

.env

(or your secret store) before closing the dialog — there's no recovery flow, only re-generation.

Advise the user to store them in

.claude/settings.local.json

(gitignored, auto-loaded by Claude Code) or in

.env

json

// .claude/settings.local.json
{
  "env": {
    "SUMSUB_APP_TOKEN": "sbx:...",
    "SUMSUB_SECRET_KEY": "..."
  }
}

bash

# .env
SUMSUB_APP_TOKEN=sbx:...
SUMSUB_SECRET_KEY=...

If either credential is missing, stop and ask. Do not invent placeholders.

The three required headers

Every request to

api.sumsub.com

must carry:

Header	Value
`X-App-Token`	The App Token, verbatim.
`X-App-Access-Ts`	Current Unix time in seconds (UTC). Must be within ±60s of Sumsub's clock.
`X-App-Access-Sig`	Lowercase hex HMAC-SHA256 of the signing string, keyed by the secret.

HTTPS is mandatory — plain

http://

is rejected.

Signing string

Concatenate, with no separators:

<ts><HTTP_METHOD_UPPER><request_uri_with_query><body_bytes_or_empty>

```
ts
```
— the exact value you put in
```
X-App-Access-Ts
```
(string of digits).
```
HTTP_METHOD_UPPER
```
—
```
GET
```
,
```
POST
```
,
```
PATCH
```
,
```
PUT
```
,
```
DELETE
```
— uppercase.

request_uri_with_query

— path starting with

, including the query string if any. Examples:

/resources/applicants/-/one

/resources/accessTokens?userId=abc&levelName=basic-kyc-level

Body — the raw bytes you send. For
```
GET
```
/
```
DELETE
```
with no body, append nothing (empty string). For JSON, sign the exact bytes you'll transmit — re-serializing later will break the signature.

Then

hex(hmac_sha256(secret, signing_string))

, lowercase.

Worked example (from the docs)

Signing string for

POST /resources/accessTokens?userId=...&levelName=basic-kyc-level&ttlInSecs=600

with no body, at ts

1607551635

1607551635POST/resources/accessTokens?userId=cfd20712-24a2-4c7d-9ab0-146f3c142335&levelName=basic-kyc-level&ttlInSecs=600

Reference implementations

The official multi-language examples live at SumSubstance/AppTokenUsageExamples (Java, JS, Python, Ruby, Go, PHP, C#). Use those for production integrations.

For one-off calls or debugging, this skill ships two small helpers:

```
scripts/sumsub_sign.py
```
— print the three headers for a given method/path/body. No network calls.

scripts/sumsub_curl.sh

— sign +

curl

in one shot. Reads

SUMSUB_APP_TOKEN

SUMSUB_SECRET_KEY

from the environment.

Run scripts using

${CLAUDE_SKILL_DIR}/scripts/<script>

so they resolve correctly regardless of the working directory.

Quick check — fetch the current applicant count

bash

export SUMSUB_APP_TOKEN='sbx:...'   # sandbox token, refuse prod
export SUMSUB_SECRET_KEY='...'

${CLAUDE_SKILL_DIR}/scripts/sumsub_curl.sh GET '/resources/applicants/-/count'

with a JSON body confirms the signature is correct. A

with

{"description":"Invalid signature"}

means the signing string or secret is off — re-check, in order:

Token/secret pair matches (copy-paste truncation is common).
Timestamp is in seconds, not milliseconds, and your clock is in sync.
Path includes the leading
```
/
```
and the full query string.
Body bytes signed are byte-identical to bytes sent (watch for trailing newlines added by editors / heredocs).
Method is uppercase.

Signing

multipart/form-data

requests

Some endpoints take a file upload — most commonly idDoc photo upload at

POST /resources/applicants/{applicantId}/info/idDoc

. For these:

Sign the full raw multipart body, byte-for-byte, including boundary markers, part headers, JSON metadata, and file bytes. There is no multipart-specific exemption — the rule is the same as for JSON: signing string =
```
ts + METHOD + path + body_bytes
```
.
The
```
Content-Type
```
header is
```
multipart/form-data; boundary=<boundary>
```
, where
```
<boundary>
```
matches the one woven into the body bytes you signed.

The pitfall: most HTTP libraries (

curl -F

requests

with

files=

fetch

with

FormData

) generate the boundary internally and never expose the exact bytes — so you cannot sign what they will send. Workaround: build the body in memory yourself, hash it, then transmit those exact bytes with

--data-binary

/ a raw send.

Python recipe (canonical)

python

import hashlib, hmac, json, os, time, uuid
from pathlib import Path
from urllib.request import Request, urlopen

APP_TOKEN = os.environ["SUMSUB_APP_TOKEN"]
SECRET    = os.environ["SUMSUB_SECRET_KEY"]
APPLICANT = "6a170f852f9d88fe6eda2636"          # from create-applicant response
FILE      = Path("/path/to/passport.png")
METADATA  = {"idDocType": "PASSPORT", "country": "RUS"}

boundary = "----sumsub-" + uuid.uuid4().hex
crlf = b"\r\n"
parts = [
    b"--" + boundary.encode(),
    b'Content-Disposition: form-data; name="metadata"',
    b"Content-Type: application/json",
    b"",
    json.dumps(METADATA).encode(),
    b"--" + boundary.encode(),
    f'Content-Disposition: form-data; name="content"; filename="{FILE.name}"'.encode(),
    b"Content-Type: image/png",
    b"",
    FILE.read_bytes(),
    b"--" + boundary.encode() + b"--",
    b"",
]
body = crlf.join(parts)

method, url_path = "POST", f"/resources/applicants/{APPLICANT}/info/idDoc"
ts = str(int(time.time()))
sig = hmac.new(
    SECRET.encode(),
    ts.encode() + method.encode() + url_path.encode() + body,
    hashlib.sha256,
).hexdigest()

req = Request(
    "https://api.sumsub.com" + url_path,
    data=body, method="POST",
    headers={
        "X-App-Token": APP_TOKEN,
        "X-App-Access-Ts": ts,
        "X-App-Access-Sig": sig,
        "Content-Type": f"multipart/form-data; boundary={boundary}",
        "Content-Length": str(len(body)),
        "X-Agent-Source": "sumsub-skills",
        "X-Agent-Source-Ver": "1.2.0",
    },
)
print(urlopen(req).read().decode())

Curl-based fallbacks (e.g.

curl --data-binary @raw-multipart.bin

after pre-building the body to disk) work too, but the boundary in the body and in

Content-Type

must match exactly — easier to keep them in sync in code.

Generating an SDK access token (common follow-up)

The most-asked endpoint after auth works:

POST /resources/accessTokens?userId=<your_user_id>&levelName=<level>&ttlInSecs=600

Body is empty. Response contains

token

— pass that to the Web / Mobile SDK. Full reference: https://docs.sumsub.com/reference/generate-access-token.

sumsub-api-auth

NPX Install

Tags

SKILL.md Content

Sumsub — API authentication (App Token)

⚠️ Sandbox tokens only

What you need from the user

The three required headers

Signing string

Worked example (from the docs)

Reference implementations

Quick check — fetch the current applicant count

Signing
`multipart/form-data`
requests

Python recipe (canonical)

Generating an SDK access token (common follow-up)

See also