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 the Web and Mobile SDKs, 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-Appheaders 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-Tsheader) taken as a string. - An HTTP method name in upper-case, e.g.
GETorPOST. - 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
GETrequests, 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: