Onfido Authentication: API Key and Webhook Security Guide

Authentication overview

Onfido provides identity verification services through its API, enabling clients to integrate document and biometric checks into their applications. Authentication primarily involves an API key for server-to-server communication, ensuring that only authorized applications can access and manipulate identity data. The client-side SDKs (Onfido mobile and web SDKs) manage the secure capture and upload of user data (documents, biometrics) directly to Onfido's platform, reducing the burden of sensitive data handling on the integrating application's backend.

For asynchronous notifications, such as when a check completes, Onfido utilizes webhooks. These webhooks deliver real-time updates to a specified endpoint on the client's server, requiring a shared secret for signature verification to ensure the authenticity and integrity of incoming payloads. This dual approach—API keys for requests and signed webhooks for notifications—establishes a secure framework for identity verification workflows.

Supported authentication methods

Onfido supports distinct authentication mechanisms for API requests and webhook verification, each tailored to its specific use case and security requirements.

Getting your credentials

To integrate with Onfido, you will need to obtain API keys and configure webhook secrets within the Onfido Dashboard.

API Keys

1. Access the Dashboard: Log in to your Onfido Dashboard.
2. Navigate to API Keys: Go to the 'Developers' section, then select 'API keys'.
3. Generate Key: Create a new API key. Onfido typically provides a 'Live' key for production environments and a 'Sandbox' key for testing and development. Best practice dictates using separate keys for different environments.
4. Record Key: The API key is typically shown only once upon creation. Copy and store it securely. Treat your API keys like passwords; they grant access to your account's data and operations.

Webhook Shared Secrets

1. Access the Dashboard: Log in to your Onfido Dashboard.
2. Navigate to Webhooks: Go to the 'Developers' section, then select 'Webhooks'.
3. Create/Edit Webhook: Configure a new webhook or edit an existing one. You will specify the URL where Onfido should send event notifications.
4. Generate Secret: When configuring the webhook, Onfido will provide a shared secret. This secret is used to generate a digital signature for each webhook payload.
5. Record Secret: Immediately copy and securely store this shared secret. Your application will use this secret to verify the signature of incoming webhooks, ensuring they originate from Onfido and have not been tampered with. For an example of how signature verification works, see Twilio's webhook security guide on validating webhook requests.

Authenticated request example

API requests to Onfido are authenticated using your API key as a Bearer token in the Authorization header. The following example demonstrates how to create an applicant using the Onfido API with a Python requests library.

import requests

ONFIDO_API_KEY = "YOUR_ONFIDO_API_KEY"  # Replace with your actual API key
ONFIDO_API_URL = "https://api.onfido.com/v3.6/applicants" # Or https://api.sandbox.onfido.com/v3.6/applicants for sandbox

headers = {
    "Authorization": f"Token token={ONFIDO_API_KEY}",
    "Content-Type": "application/json"
}

data = {
    "first_name": "Jane",
    "last_name": "Doe",
    "dob": "1990-01-01",
    "country": "GBR"
}

try:
    response = requests.post(ONFIDO_API_URL, headers=headers, json=data)
    response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)
    applicant_data = response.json()
    print("Applicant created successfully:")
    print(applicant_data)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
    if response is not None:
        print(f"Response Status Code: {response.status_code}")
        print(f"Response Body: {response.text}")

In this example, YOUR_ONFIDO_API_KEY must be replaced with a valid API key obtained from your Onfido dashboard. The Authorization header correctly formats the Bearer token for server-side communication.

Security best practices

Securing your Onfido integration requires careful management of credentials and robust handling of webhook events. Adhering to these best practices helps protect your application and user data:

• API Key Management:
  • Environment Variables: Store API keys as environment variables rather than hardcoding them directly into your application's source code. This prevents keys from being exposed in version control systems.
  • Separate Keys: Use distinct API keys for different environments (development, staging, production) and, if possible, for different services or modules within your application.
  • Rotation: Regularly rotate your API keys. If a key is compromised, rotation ensures that the old key quickly becomes invalid.
  • Principle of Least Privilege: If Onfido supports it, generate API keys with only the necessary permissions required for the specific tasks they perform.
• Webhook Security:
  • Signature Verification: Always verify the signature of incoming webhooks using the shared secret. This confirms that the webhook originated from Onfido and that its payload has not been altered during transit. Implementations typically involve hashing the raw request body with the shared secret and comparing it to the signature provided in the webhook's headers, as detailed in the Onfido webhook security documentation.
  • HTTPS Endpoints: Ensure your webhook endpoint uses HTTPS to encrypt data in transit, protecting against eavesdropping.
  • Idempotency: Design your webhook handlers to be idempotent. This means that processing the same webhook event multiple times will not lead to unintended side effects. Onfido may occasionally send duplicate events.
  • Asynchronous Processing: Process webhook events asynchronously to avoid timeout issues if Onfido's servers don't receive a timely 2xx response. Queue events and process them in the background.
• Secure Communication:
  • HTTPS Everywhere: All communication with Onfido's API and your webhook endpoints should occur over HTTPS to ensure data encryption in transit.
  • Firewall Rules: Restrict network access to your webhook endpoints and API-consuming services to known Onfido IP ranges, if provided and feasible.
• Error Handling and Logging:
  • Implement robust error handling for API responses and webhook processing. Log relevant information (without exposing sensitive data) for debugging and auditing purposes.
• Compliance:
  • Maintain compliance with relevant data protection regulations (e.g., GDPR, CCPA) and industry standards (e.g., SOC 2 Type II, ISO 27001) in your handling of identity verification data and credentials. Onfido's platform is designed to assist with these compliance requirements, but your integration must also adhere to them.