API ReferenceChangelogFAQDashboard

Authentication

To start working with the Sumsub API, all clients must authenticate themselves.

Generate app token

An app token is a secure method of communication with our API. You can create an app token in the Dashboard, as described in this article.

📘

Note

The full-sized app token and secret key values are shown in the Dashboard only once — at the moment you create the token; make sure to save it to a secure location on your device. Once created, you will not be able to make any changes.

👍

Tip

To learn more on how to generate an app token for WebSDK and MobileSDKs, see this article.

Make requests

All requests must contain the following headers:

  • X-App-Token — an app token that you generate in the Dashboard.
  • X-App-Access-Sig — a request signature in the HEX format and lowercase.
  • X-App-Access-Ts — a number of seconds since Unix Epoch in UTC.

🚧

Attention

All API queries must be sent over HTTPS; plain HTTP will be refused. You must include your X-App headers in all requests.

Sign requests

The value of the X-App-Access-Sig header is generated with the sha256 HMAC algorithm using a secret key (provided upon app token generation) on the bytes obtained by concatenating the following information:

  • A timestamp (value of the X-App-Access-Ts header) taken as a string.
  • An HTTP method name in upper-case, e.g. GET or POST.
  • URI of the request without a host name, starting with a slash and including all query parameters, e.g. /resources/applicants/123?fields=info
  • Request body, taken exactly as it will be sent. If there is no request body, e.g., for GET requests, do not include it.

The following is an example of the string to be signed to get an access token:

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

📘

Note

Your timestamp must be within 1 minute of the API server time. Make sure the time on your servers is correct.

Examples of how you can sign your requests:

Rate limits

A rate limit is the number of API calls an app or user can make within a given time period.

The current default rate limits are:

  • For GET requests — 300.0 per 5.0 seconds.
  • For POST requests — 50.0 per 5.0 seconds.

📘

Note

We can increase these limits upon individual requests.