Humanitarian Data Exchange Authentication: API Access (2026)

Authentication overview

The Humanitarian Data Exchange (HDX) API provides programmatic access to a wide range of humanitarian datasets, enabling developers and data analysts to integrate critical information into their applications and research. Authentication for the HDX API is primarily managed through API keys, which are unique tokens assigned to user accounts. These keys serve as a credential to verify the identity of the requesting application or user, granting access to public datasets and, for authenticated users, potentially enabling data submission or management functionalities depending on permissions. The HDX API is built on the CKAN platform, and its authentication mechanisms align with CKAN's standard practices for API key management, ensuring a consistent and secure method for accessing humanitarian data resources programmatically. For detailed API specifications, refer to the Humanitarian Data Exchange API documentation.

The HDX platform emphasizes open data principles, meaning a significant portion of its data is publicly accessible without prior authentication. However, using an API key provides several benefits, including higher rate limits, improved request traceability, and the ability to interact with certain authenticated endpoints. This approach helps the HDX team monitor API usage, prevent abuse, and ensure fair access to resources across its user base. Understanding the authentication process is crucial for developers building robust applications that interact with the HDX ecosystem.

Supported authentication methods

The Humanitarian Data Exchange API primarily supports API key authentication. This method involves generating a unique token within your HDX user account and including it in the headers of your API requests. While other authentication methods like OAuth 2.0 or basic authentication are common in many APIs, HDX's focus on open data and its CKAN-based architecture streamlines access through API keys for most use cases.

API Key Authentication

• Mechanism: A secret token generated by the user and sent with each API request.
• Purpose: Identifies the user or application making the request and verifies authorization for specific actions or higher rate limits.
• How it works: The API key is typically passed in the Authorization header of an HTTP request.
• Security Considerations: API keys should be treated as sensitive credentials, similar to passwords, and protected from unauthorized access.

The following table summarizes the primary authentication method supported by the HDX API:

For scenarios requiring secure delegation of access without sharing user credentials, more complex authentication flows like OAuth 2.0 are often employed by other platforms. However, for direct API access to HDX, the API key system is the established and supported method. For general information on API key security, consult resources like the Cloudflare API key security guide.

Getting your credentials

To obtain an API key for the Humanitarian Data Exchange, you must first have an active user account on the HDX platform. The process involves registering for an account, if you don't already have one, and then navigating to your user profile settings to generate the key. This ensures that the API key is linked directly to your identity and permissions within the HDX ecosystem.

Step-by-step guide to generating an HDX API key:

1. Register or Log In: Visit the Humanitarian Data Exchange website and either create a new account or log in to an existing one. Account creation typically requires a valid email address and setting a password.
2. Access Your Profile: Once logged in, navigate to your user profile. This is usually accessible through a dropdown menu under your username or an icon in the top right corner of the page. Look for an option like "My Profile" or "Account Settings."
3. Find API Key Section: Within your profile settings, there should be a dedicated section for API keys or API tokens. The exact naming might vary slightly, but it will be clearly labeled.
4. Generate New Key: If you don't have an existing key, or if you need a new one (e.g., for security rotation), there will be an option to "Generate New API Key" or similar. Clicking this button will create a unique alphanumeric string.
5. Copy and Secure Your Key: Once generated, the API key will be displayed. It is crucial to copy this key immediately and store it securely. For security reasons, the key may only be displayed once, and you might not be able to retrieve it again if you lose it. Treat your API key with the same level of confidentiality as you would a password.
6. Revoke Old Keys (Optional): If you are generating a new key to replace an old one, or if you suspect an existing key has been compromised, you should revoke the old key from the same API key management section. This invalidates the old key, preventing its further use.

The generated API key is a long, randomly generated string of characters. This key will be used in your API requests to authenticate with the HDX server. It's important to note that the HDX platform provides all data access for free, so the API key primarily serves for identification, rate limiting, and potentially access to specific user-contributed or restricted functionalities if applicable. Always refer to the official HDX API documentation for the most up-to-date instructions on credential management.

Authenticated request example

Once you have obtained your API key from the Humanitarian Data Exchange platform, you can use it to make authenticated requests to the HDX API. The API key is typically passed in the Authorization header of your HTTP request. The specific header format follows a common pattern used in many web APIs.

Here's a breakdown of how to construct an authenticated request using Python, a common language for data interaction, and the requests library:

Python Example

import requests
import os

# It's best practice to store your API key as an environment variable
# For demonstration, we'll use a placeholder. Replace 'YOUR_HDX_API_KEY' with your actual key.
HDX_API_KEY = os.environ.get('HDX_API_KEY', 'YOUR_HDX_API_KEY')

# Define the API endpoint you want to access
# Example: Fetching a list of packages (datasets)
api_url = "https://data.humdata.org/api/3/action/package_list"

# Set up the headers with your API key
headers = {
    "Authorization": HDX_API_KEY
}

try:
    # Make the GET request to the API
    response = requests.get(api_url, headers=headers)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)

    # Parse the JSON response
    data = response.json()

    # Print some of the retrieved data
    print("Successfully authenticated and retrieved data.")
    print(f"First 5 dataset IDs: {data['result'][:5]}")

except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
    print(f"Response content: {response.text}")
except requests.exceptions.RequestException as e:
    print(f"An error occurred during the request: {e}")

Explanation:

• HDX_API_KEY: This variable should hold the API key you generated from your HDX account. It's recommended to load this from an environment variable (as shown with os.environ.get) rather than hardcoding it directly into your script.
• api_url: This is the specific HDX API endpoint you intend to call. The example uses package_list to retrieve a list of dataset IDs, a common starting point for exploring the API.
• headers: A Python dictionary where the key "Authorization" is mapped to your HDX_API_KEY. The HDX API expects the key to be directly in this header without additional prefixes like Bearer.
• requests.get(api_url, headers=headers): This line performs the actual HTTP GET request, including your authentication header.
• response.raise_for_status(): This is a crucial step for error handling. It checks if the HTTP response status code indicates an error (e.g., 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error). If an error occurs, it raises an HTTPError.
• response.json(): If the request is successful, this method parses the JSON response body into a Python dictionary or list.

For more detailed examples and specific endpoint usage, always consult the Humanitarian Data Exchange API reference.

Security best practices

Securing your API keys and ensuring the integrity of your interactions with the Humanitarian Data Exchange API is paramount. While HDX focuses on open data, protecting your credentials helps maintain the reliability of your applications and prevents unauthorized access to your account or potential misuse of API resources. Adhering to general API security principles, as outlined by organizations like the OWASP API Security Project, is crucial.

Key management and storage:

• Treat API Keys as Passwords: Your HDX API key grants access to your account's API capabilities. Never hardcode API keys directly into your source code.
• Use Environment Variables: Store API keys as environment variables on your server or local development machine. This keeps them out of your codebase and version control systems (e.g., Git). Most programming languages offer simple ways to access environment variables.
• Secure Configuration Files: If environment variables are not feasible, use secure configuration files that are not committed to version control. Ensure these files have strict file system permissions.
• Secrets Management Services: For production environments, consider using dedicated secrets management services (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault, HashiCorp Vault) to securely store and retrieve API keys dynamically.
• Restrict Access: Limit who has access to your API keys. Only individuals or systems that absolutely require the key for operation should have access.

Transmission and network security:

• Always Use HTTPS: Ensure all API requests to the HDX API are made over HTTPS. This encrypts the communication channel between your application and the HDX server, protecting your API key and data from interception during transit. The HDX API inherently uses HTTPS.
• Avoid Public Networks: When possible, avoid transmitting or managing API keys over unsecured public Wi-Fi networks.

Error handling and logging:

• Do Not Log API Keys: Never log your API keys in plain text. If logging is necessary for debugging, ensure the key is redacted or masked.
• Monitor for Unauthorized Access: Implement logging and monitoring for API request failures (e.g., 401 Unauthorized errors) to detect potential misuse or compromise of your API key.

Key rotation and revocation:

• Regular Key Rotation: Periodically generate a new API key and replace the old one in your applications. This reduces the window of opportunity for a compromised key to be exploited.
• Immediate Revocation: If you suspect your API key has been compromised, immediately revoke it from your HDX account settings and generate a new one. Update all applications using the compromised key with the new one.

Least privilege:

• Minimal Permissions: While HDX API keys primarily grant access to public data, if there were any features requiring specific permissions (e.g., data submission), always ensure your key has only the minimum necessary permissions required for its intended function.

By following these best practices, you can significantly enhance the security posture of your applications interacting with the Humanitarian Data Exchange API, protecting both your credentials and the integrity of the data you access.