Authentication overview

OpenSanctions provides an API to access its comprehensive sanctions, watchlist, and politically exposed person (PEP) data. Authentication for the OpenSanctions API is primarily managed through API keys, which serve as tokens to verify a client's identity and authorize access to data and services. This method ensures that only authorized applications and users can query the dataset, supporting compliance and due diligence workflows. All API interactions are expected to occur over HTTPS to protect the confidentiality and integrity of data in transit, aligning with industry-standard secure communication protocols like those recommended by the W3C on web security.

The API key system is integrated into OpenSanctions's infrastructure, allowing users to generate, manage, and revoke their keys through a dedicated account dashboard. This self-service approach facilitates quick integration and provides users with direct control over their access credentials. OpenSanctions supports both commercial and non-commercial usage, with different access tiers and associated API key permissions, as detailed in the OpenSanctions pricing page. Non-commercial users can access the API for free, while commercial entities typically subscribe to paid plans starting at €250 per month, which include enhanced API access and support.

Supported authentication methods

OpenSanctions primarily utilizes API keys for authenticating requests to its data API. This method is common for RESTful APIs due to its simplicity and effectiveness in managing access to specific resources. While API keys are the standard, the platform's focus on data downloads also implies mechanisms for authenticated access to bulk data files, often secured through the same credentialing system.

The following table outlines the primary authentication method supported by OpenSanctions:

Method Description When to Use Security Level
API Key A unique alphanumeric string passed in the Authorization header or as a query parameter. Programmatic access to the OpenSanctions API for querying entities, names, and lists. Suitable for server-to-server communication or backend services. Moderate. Requires secure handling and storage to prevent unauthorized access. Always use over HTTPS.

The choice of API key authentication aligns with the need for straightforward, stateless authorization for data retrieval services. This method is particularly well-suited for applications that integrate OpenSanctions data into their backend processes for AML/KYC screening, due diligence, or investigative journalism, where client-side exposure of credentials is avoided.

Getting your credentials

To obtain your OpenSanctions API key, you need to register for an account on the OpenSanctions website. The process typically involves:

  1. Account Registration: Navigate to the OpenSanctions homepage and sign up for a new account. You will likely need to provide an email address and create a password.
  2. Plan Selection: Depending on your intended use (commercial vs. non-commercial), you may need to select an appropriate plan. Non-commercial users can often access a free tier that includes API access, while commercial users will subscribe to a paid plan.
  3. Accessing Dashboard: Once registered and logged in, you will gain access to your user dashboard. This dashboard is the central location for managing your account, subscriptions, and API keys.
  4. Generating API Key: Within the dashboard, there will be a section dedicated to API keys or developer settings. Here, you can generate a new API key. It is crucial to copy this key immediately upon generation, as it may not be displayed again for security reasons.
  5. Storing Your Key: Securely store your API key. Treat it like a password. Do not embed it directly in client-side code, commit it to version control, or expose it in public repositories.

For detailed, step-by-step instructions on account creation and API key generation, refer to the OpenSanctions documentation. The documentation provides specific guidance tailored to the current platform interface.

Authenticated request example

Once you have obtained your API key, you can use it to authenticate your requests to the OpenSanctions API. The API key is typically included in the Authorization header of your HTTP request. Below is an example using curl to query the OpenSanctions API for an entity, demonstrating how to include your API key securely.

Replace YOUR_API_KEY with your actual OpenSanctions API key and adjust the query parameters as needed.

curl -X GET \
  'https://api.opensanctions.org/v1/entities?q=Vladimir%20Putin' \
  -H 'Accept: application/json' \
  -H 'Authorization: Apikey YOUR_API_KEY'

In this example:

  • -X GET specifies the HTTP method.
  • 'https://api.opensanctions.org/v1/entities?q=Vladimir%20Putin' is the API endpoint being accessed, with a query parameter q for searching.
  • -H 'Accept: application/json' indicates that the client expects a JSON response.
  • -H 'Authorization: Apikey YOUR_API_KEY' is the critical authentication header. The scheme Apikey (note the capitalization) is followed by a space and then your actual API key.

Always ensure your API key is correctly formatted and included in the Authorization header for all authenticated requests. Incorrect formatting or missing keys will result in unauthorized access errors.

Security best practices

Securing your API keys and managing access to the OpenSanctions API is paramount to protect your data and prevent unauthorized usage. Adhering to security best practices helps mitigate risks associated with API key exposure and misuse. These practices are standard across many API platforms, including those detailed in AWS access key best practices.

API Key Management

  • Keep Keys Confidential: Treat your API key as sensitive as a password. Never embed it directly in client-side code (e.g., JavaScript in a browser), mobile applications, or public repositories.
  • Environment Variables: Store API keys as environment variables on your server or in secure configuration files. This prevents them from being hardcoded into your application's source code.
  • Key Rotation: Periodically rotate your API keys. Generate a new key and update your applications, then revoke the old key. This limits the window of exposure if a key is compromised.
  • Least Privilege: If OpenSanctions offers granular permissions (though primarily a data retrieval API, this principle applies generally), ensure your API key only has the minimum necessary permissions required for its intended function.
  • Monitoring: Monitor API usage patterns. Unusual spikes in requests or access from unexpected locations could indicate a compromised key.

Secure Communication

  • Always Use HTTPS: All communication with the OpenSanctions API must occur over HTTPS (TLS). This encrypts data in transit, protecting your API key and the data you retrieve from eavesdropping. OpenSanctions enforces HTTPS for all API endpoints.
  • Validate SSL Certificates: Ensure your application is configured to validate SSL/TLS certificates. This prevents man-in-the-middle attacks where an attacker might try to impersonate the OpenSanctions API.

Application Security

  • Input Validation: Sanitize and validate all inputs sent to the OpenSanctions API to prevent injection attacks or malformed requests.
  • Error Handling: Implement robust error handling in your application. Avoid logging sensitive information, such as API keys, in error messages or application logs that might be publicly accessible.
  • Rate Limiting: Be aware of and respect OpenSanctions's API rate limits. Excessive requests can lead to temporary blocking, which, while not a security issue, can impact service availability.

By implementing these security best practices, developers can significantly enhance the protection of their OpenSanctions API integrations and ensure the secure handling of sensitive sanctions data.