Sumsub Authentication: API Security & Credential Management

Authentication overview

Sumsub's API authentication framework is designed to ensure secure and verifiable interactions for identity verification, AML screening, and fraud prevention services. The primary mechanism for authenticating requests to the Sumsub API involves signed requests, leveraging a combination of an API Key and an API Secret. This approach utilizes HMAC-SHA256 (Hash-based Message Authentication Code using SHA256) to generate a unique signature for each request, verifying both the sender's identity and the integrity of the transmitted data. This method is a common practice for securing RESTful APIs, providing protection against tampering and unauthorized access.

The system requires clients to include specific headers in their HTTP requests, which are then used by the Sumsub server to validate the signature against a re-computed hash. This process ensures that only requests originating from an authorized source with the correct credentials are processed. For client-side operations, such as integrating the Web SDK or mobile SDKs, Sumsub typically employs a token-based authentication flow, where a temporary access token is generated server-side and then used by the client to interact with the Sumsub services securely.

Understanding the distinction between server-to-server API authentication and client-side SDK authentication is crucial for implementing secure and compliant identity verification workflows. Server-to-server interactions generally involve the more robust signed request method, while client-side SDKs abstract much of the authentication complexity, relying on securely provisioned tokens to manage user sessions and data submission.

Supported authentication methods

Sumsub primarily supports authenticated requests through HMAC-SHA256 signatures for direct API interactions, while its SDKs utilize client tokens for secure client-side operations. The choice of method depends on the integration point and the desired security posture.

API Key & Secret (HMAC-SHA256 Signed Requests)

This is the standard and most secure method for server-to-server communication with the Sumsub API. It involves generating a cryptographic signature for each request using your unique API Key and API Secret. The signature is computed over a canonical representation of the request (including HTTP method, path, query parameters, request body, and timestamp) and then included in the X-Sumsub-Hmac-Signature header. This mechanism ensures:

• Authentication: Verifies the identity of the client making the request.
• Integrity: Confirms that the request data has not been altered in transit.
• Replay Protection: Timestamps within the signature help mitigate replay attacks.

Detailed steps for constructing signed requests are available in the Sumsub API authentication guide. This method aligns with common practices for securing RESTful APIs, similar to how AWS signs its API requests, as outlined in the AWS Signature Version 4 process.

Client Tokens (for SDKs)

When integrating Sumsub via its client-side SDKs (Web SDK, Android SDK, iOS SDK, Flutter, React Native), authentication is handled through temporary client tokens. These tokens are generated on your backend server using your API Key and Secret and then passed to the client-side SDK. The client token grants temporary, scoped access for a specific applicant, allowing the SDK to securely interact with Sumsub services without exposing your sensitive API Secret.

• Server-side Generation: Your backend generates a client token by making an authenticated request to the Sumsub API.
• Client-side Usage: The SDK uses this token to initialize the identity verification flow, upload documents, and communicate securely with Sumsub.
• Reduced Exposure: Your API Key and Secret remain secure on your server, never exposed to the client application.

For more information on client tokens and SDK integration, refer to the Sumsub Client Tokens documentation.

Authentication Methods Summary

Getting your credentials

To begin authenticating with Sumsub, you need to obtain your API Key and API Secret. These credentials are generated within your Sumsub Dashboard. Follow these steps:

1. Log in to the Sumsub Dashboard: Access your account at https://sumsub.com/login.
2. Navigate to Integration Settings: In the dashboard, typically find a section like 'Developers' or 'Integration' in the left-hand navigation pane.
3. Generate API Keys: Locate the 'API Keys' or 'Keys' subsection. You will usually have the option to generate a new pair of API Key and API Secret.
4. Securely Store Credentials: Upon generation, the API Secret is typically shown only once. It is crucial to copy and store it immediately in a secure location, such as an environment variable or a secrets management service. Do not hardcode credentials directly into your application code or commit them to version control.
5. Configure Webhooks (Optional but Recommended): While not strictly authentication credentials, configuring webhooks is vital for receiving real-time updates from Sumsub. You will also generate a separate webhook secret in the dashboard to verify the authenticity of incoming webhook payloads. This prevents your system from processing fraudulent webhook notifications.

For precise instructions and visual guidance, consult the Sumsub guide on obtaining API keys.

Authenticated request example

This Python example demonstrates how to create an applicant and sign the request using HMAC-SHA256, assuming you have your APP_TOKEN (API Key) and SECRET_KEY (API Secret) configured securely. The requests library is used for HTTP communication and hmac for cryptographic hashing.

import requests
import hmac
import hashlib
import time
import json
import os

# --- Configuration (replace with your actual credentials) ---
APP_TOKEN = os.getenv("SUMSUB_APP_TOKEN") # Your API Key
SECRET_KEY = os.getenv("SUMSUB_SECRET_KEY").encode('utf-8') # Your API Secret
BASE_URL = "https://api.sumsub.com"

# --- Request details ---
method = "POST"
path = "/resources/applicants"
body = {
    "externalUserId": "user_12345",
    "phone": "+1234567890",
    "email": "[email protected]"
}

# --- Helper function to create the signature ---
def create_signature(method, path, body, secret_key):
    # 1. Get current timestamp
    ts = str(int(time.time()))

    # 2. Prepare the request body for hashing
    body_str = json.dumps(body, separators=(',', ':')) if body else ''
    body_bytes = body_str.encode('utf-8')

    # 3. Concatenate components for signing
    # Sumsub signature string format: timestamp + method.upper() + path + body_str
    data_to_sign = (ts + method.upper() + path + body_str).encode('utf-8')

    # 4. Generate HMAC-SHA256 signature
    signature = hmac.new(secret_key, data_to_sign, hashlib.sha256).hexdigest()
    
    return ts, signature

# --- Main execution ---
if __name__ == "__main__":
    if not APP_TOKEN or not SECRET_KEY:
        print("Error: SUMSUB_APP_TOKEN or SUMSUB_SECRET_KEY environment variables not set.")
        exit(1)

    url = BASE_URL + path
    ts, signature = create_signature(method, path, body, SECRET_KEY)

    headers = {
        "Content-Type": "application/json",
        "X-App-Token": APP_TOKEN,
        "X-Sumsub-Hmac-Digest": signature,
        "X-Sumsub-Request-Ts": ts
    }

    try:
        response = requests.request(method, url, headers=headers, data=json.dumps(body))
        response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
        print("Request successful!")
        print("Status Code:", response.status_code)
        print("Response Body:", json.json_util.dumps(response.json(), indent=2))

    except requests.exceptions.HTTPError as e:
        print(f"HTTP Error: {e.response.status_code} - {e.response.text}")
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")

This example demonstrates the core principles: constructing the data to sign, generating the HMAC digest, and including the necessary headers (X-App-Token, X-Sumsub-Hmac-Digest, X-Sumsub-Request-Ts) in the HTTP request. For a complete list of endpoints and detailed request/response schemas, refer to the official Sumsub API Reference.

Security best practices

Implementing strong security measures for your Sumsub integration is paramount to protect sensitive user data, maintain compliance, and prevent fraud.

Credential Management

• Environment Variables/Secrets Management: Never hardcode your API Key or API Secret directly into your source code. Use environment variables (e.g., SUMSUB_APP_TOKEN, SUMSUB_SECRET_KEY) or a dedicated secrets management service (e.g., AWS Secrets Manager, Google Secret Manager, HashiCorp Vault) to store and retrieve credentials securely.
• Least Privilege: If Sumsub offers different types of API keys or roles, provision keys with only the minimum necessary permissions required for their intended function.
• Key Rotation: Regularly rotate your API Keys and Secrets (e.g., every 90 days) to minimize the impact of a potential compromise. Sumsub's dashboard typically allows you to generate new keys and revoke old ones.
• Revocation: Immediately revoke any compromised or no longer needed API keys from your Sumsub Dashboard.

API Request Security

• HTTPS Only: Always use HTTPS for all communications with the Sumsub API to ensure data encryption in transit. Sumsub's API implicitly enforces this.
• Timestamp Verification: The X-Sumsub-Request-Ts header is crucial for replay protection. Ensure your system's clock is synchronized using NTP (Network Time Protocol) to avoid signature validation failures due to time drift.
• Validate Webhook Signatures: If you use webhooks, always verify the X-Sumsub-Hmac-Digest header in incoming webhook requests against your webhook secret. This confirms that the webhook payload genuinely originated from Sumsub and has not been tampered with. For details, see the Sumsub webhook security guide.
• Error Handling: Implement robust error handling for API responses, particularly for authentication or authorization errors (e.g., 401 Unauthorized, 403 Forbidden).

Application and Infrastructure Security

• Input Validation: Sanitize and validate all user inputs before sending them to the Sumsub API to prevent injection attacks and ensure data quality.
• Logging and Monitoring: Implement comprehensive logging for API requests and responses, especially failed authentication attempts. Monitor these logs for suspicious activity.
• Network Security: Restrict network access to your application servers that interact with the Sumsub API, using firewalls and security groups.
• Principle of Least Privilege (System Access): Ensure that only authorized personnel and systems have access to your Sumsub credentials and the code interacting with the API.
• SDK Security: When using client-side SDKs, ensure you are using the latest versions to benefit from security patches and improvements. Always generate client tokens on your secure backend server, never directly from the client-side.
• Compliance: Adhere to relevant data protection regulations such as GDPR, CCPA, and industry-specific compliance standards like SOC 2 Type II and ISO 27001, which Sumsub itself is compliant with. Understand your obligations regarding the handling of Personally Identifiable Information (PII) passed to and received from Sumsub.