Veriff Authentication: API Security & Credential Management

Authentication overview

Veriff's API authentication system is designed to secure communications between client applications and the Veriff platform, particularly when initiating identity verification sessions or retrieving verification results. The primary method for authenticating requests to the Veriff API involves the use of API keys. These keys serve as a credential that identifies the calling application and authorizes its access to specific Veriff services and data associated with the account. All API interactions with Veriff must occur over HTTPS to ensure data encryption in transit, protecting sensitive information from interception and tampering. This adherence to secure transport protocols is a fundamental component of Veriff's overall security posture, aligning with industry best practices for API security, as detailed in the HTTP/1.1 Message Syntax and Routing specification.

API keys are generated and managed within the Veriff Partner Portal, providing a centralized location for developers to create, revoke, and manage their access credentials. Each API key is typically associated with a specific Veriff environment, such as a sandbox for testing or a live production environment. This segregation helps prevent accidental misuse of production credentials during development and testing phases. Veriff also offers client-side SDKs for iOS, Android, and Web platforms which streamline the integration process and often handle the underlying API key management and secure communication protocols, abstracting some of the complexity from the developer while maintaining security standards.

The system is built to support various integration patterns, from direct server-to-server API calls to client-side integrations facilitated by the SDKs. Regardless of the integration method, proper handling and protection of API keys are paramount to maintaining the security and integrity of the identity verification workflow. Misconfigured or exposed API keys can lead to unauthorized access to Veriff services or sensitive user data, underscoring the importance of following Veriff's security guidelines for credential management.

Supported authentication methods

Veriff primarily utilizes API keys for authenticating requests to its platform. This method is suitable for both server-side and client-side integrations, with the latter often leveraging Veriff's dedicated SDKs to manage the secure transmission of these keys and related data. The choice of method depends on the integration architecture and security requirements.

The following table outlines the main authentication approaches supported by Veriff:

For server-side integrations, API keys are typically passed in the X-AUTH-CLIENT HTTP header for most API endpoints, particularly when creating a new verification session. The Veriff SDKs simplify this process for client-side applications by providing methods to initialize a verification flow with the necessary credentials, abstracting the direct header manipulation. For instance, a session token obtained from a server-side API call is often used by the client-side SDK to connect to the specific verification session. This token-based approach enhances security by limiting the lifespan and scope of client-side credentials.

Veriff's commitment to security extends to its compliance certifications, including ISO 27001, GDPR, and SOC 2 Type II, which collectively indicate robust information security management systems and data protection practices. These certifications affirm that Veriff's infrastructure and processes, including authentication mechanisms, meet recognized international and industry standards for handling sensitive data.

Getting your credentials

To begin integrating with Veriff and obtain your API credentials, you must first register for a Veriff account. Once registered, you will gain access to the Veriff Partner Portal, which serves as your central hub for managing all aspects of your Veriff integration, including API keys. The process typically involves these steps:

1. Account Registration: Sign up for a Veriff account on their official website. Depending on your use case, you might start with a starter tier or directly engage for enterprise pricing.
2. Access the Partner Portal: After successful registration and login, navigate to the Veriff Partner Portal. This portal is where you can configure your integration settings, view verification statistics, and manage your API keys.
3. Generate API Keys: Within the Partner Portal, locate the section dedicated to API settings or developer tools. Here, you will find options to generate new API keys. Veriff typically provides distinct keys for different environments, such as a sandbox (test) key and a production (live) key. It is crucial to use the appropriate key for each environment to avoid unintended operations on live data or exceeding test limits.
4. Record Your Key: Upon generation, your API key will be displayed. It is critical to copy this key immediately and store it securely. For security reasons, Veriff often displays the full key only once, and you may not be able to retrieve it again from the portal if lost. If a key is lost or compromised, you should revoke it and generate a new one.

Veriff's API key management documentation provides detailed instructions on how to generate, manage, and revoke your API keys, along with recommendations for secure storage and usage. It is recommended to create separate API keys for different applications or environments to enhance security and simplify key rotation and revocation processes. This practice aligns with the principle of least privilege, ensuring that each application only has access to the resources it strictly needs.

Authenticated request example

When making API calls to Veriff, your API key must be included in the request headers for authentication. The following example demonstrates how to create a new verification session using cURL, a common command-line tool for making HTTP requests. This example assumes you have obtained a valid API key from your Veriff Partner Portal.

In this example, replace YOUR_API_KEY with your actual Veriff API key and adjust the payload as necessary for your specific verification requirements. The X-AUTH-CLIENT header is where your API key is transmitted.

curl -X POST \
  'https://magic.veriff.me/v1/sessions' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: YOUR_API_KEY' \
  -d '{
    "verification": {
      "vendorData": "unique-session-id-123",
      "person": {
        "firstName": "John",
        "lastName": "Doe"
      },
      "document": {
        "type": "PASSPORT"
      },
      "timestamp": "2026-05-29T10:00:00.000Z",
      "features": [
        {
          "name": "face-match"
        },
        {
          "name": "document-match"
        }
      ]
    }
  }'

This request initiates a new verification session, providing initial details about the person and the document type expected. Upon a successful request, Veriff responds with a session URL and a session ID, which are then used to direct the end-user to the verification flow, often through one of Veriff's SDKs. The full Veriff API Reference for creating a new verification session provides comprehensive details on required parameters and possible responses.

For integrations using one of Veriff's SDKs (Web, iOS, Android), the process of sending the API key might be abstracted. For instance, the Web SDK might be initialized with the API key, and subsequent calls to create or manage verification sessions would then implicitly use this key. However, for server-side operations, explicitly including the X-AUTH-CLIENT header is the standard practice.

Security best practices

Securing your Veriff API integration is critical due to the sensitive nature of identity verification data. Adhering to security best practices helps protect your API keys, prevent unauthorized access, and ensure the integrity of your verification processes. The following recommendations are essential:

• Protect API Keys: Treat your Veriff API keys like sensitive credentials such as passwords. Do not hardcode them directly into client-side code (e.g., JavaScript in a public repository or mobile app binaries) or commit them to public version control systems. Store them in environment variables, secure configuration files, or a dedicated secret management service.
• Use Environment-Specific Keys: Always use separate API keys for your development, staging, and production environments. This practice minimizes the blast radius if one key is compromised. If a development key is exposed, it won't affect your live production systems. Veriff's API key management documentation advises on this.
• Server-Side Session Creation: For most applications, it is a stronger security practice to initiate verification sessions from your backend server rather than directly from the client-side. Your server can then securely send the session ID to the client, which uses it with the Veriff SDK to complete the verification. This prevents your API key from being exposed to the client-side.
• Secure Communication (HTTPS/TLS): Always ensure that all communications with the Veriff API occur over HTTPS. Veriff enforces this, but it's a fundamental principle for any API interaction involving sensitive data. This encrypts data in transit, protecting it from eavesdropping and tampering. The Mozilla Developer Network's guide on Transport Layer Security (TLS) provides a good overview of this protocol.
• Implement IP Whitelisting: If supported by Veriff (check their portal for this feature), configure IP whitelisting for your API keys. This restricts API calls to only originate from a predefined set of IP addresses, significantly reducing the risk of unauthorized access even if a key is compromised.
• Regular Key Rotation: Periodically rotate your API keys. This practice minimizes the window of opportunity for a compromised key to be exploited. The frequency of rotation should be determined by your organization's security policies and risk assessment.
• Monitor API Usage: Regularly monitor your API usage logs for any unusual activity. Spikes in requests, requests from unexpected geographical locations, or failed authentication attempts could indicate a security incident.
• Error Handling: Implement robust error handling without exposing sensitive information in error messages. Generic error messages are preferred to avoid providing clues to potential attackers.
• Principle of Least Privilege: Grant your API keys only the necessary permissions required for their intended function. While Veriff API keys typically grant broad access to an account, this principle should be applied to your overall application architecture.
• Stay Updated: Keep your Veriff SDKs and any related libraries updated to their latest versions. Updates often include security patches and improvements that address newly discovered vulnerabilities.

By diligently applying these best practices, developers can significantly enhance the security posture of their Veriff integrations, protecting both their applications and their users' sensitive identity data.