Censys Authentication: API Keys and Account Security (2026)

Authentication overview

Censys provides programmatic access to its internet-wide scan data and attack surface management capabilities through a RESTful API. Authentication for the Censys API is managed primarily through the use of API keys and API secrets. These credentials are required for all requests that access protected resources or modify account-specific data. Adhering to secure authentication practices is critical to prevent unauthorized access to your Censys account and the sensitive data it contains.

The Censys API leverages standard web protocols, ensuring that all authenticated communication is secured via HTTPS/TLS, which encrypts data in transit and protects against eavesdropping and tampering. Developers can interact with the API directly using HTTP clients like cURL or through official SDKs available for Python and Go, which abstract the underlying HTTP requests and simplify credential handling. The Censys API reference details the specific endpoints and required authentication headers for each operation.

Supported authentication methods

Censys primarily utilizes API key-based authentication. This method involves generating a unique pair of credentials (an API ID and an API Secret) from your Censys account. These credentials are then included in the headers of your API requests to verify your identity and authorize your access.

The API key and secret together act as a form of username and password for API access. When making a request, the API ID is typically passed as a header (e.g., X-API-ID or CENSYS_API_ID) and the API secret as another header (e.g., X-API-Secret or CENSYS_API_SECRET). Both must be valid and correspond to an active Censys account for the request to be successfully authenticated.

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

Getting your credentials

To obtain your API key and secret, you must have an active Censys account. If you are using the Censys Search Community Edition or a paid tier, you can generate these credentials through your account settings portal.

1. Log in to your Censys account: Navigate to the Censys login page and enter your username and password.
2. Access API settings: Once logged in, go to your account settings or profile section. Look for a dedicated 'API' or 'API Keys' tab. The specific navigation path may vary slightly but typically involves clicking on your profile icon or name in the top right corner.
3. Generate new API credentials: Within the API settings, you will find an option to generate a new API ID and API Secret. Censys typically provides a button or link for this action. Upon generation, both the API ID and API Secret will be displayed. It is crucial to copy and store your API Secret immediately, as it is often only shown once for security reasons and cannot be retrieved later. If lost, you will need to revoke the old key and generate a new one.
4. Store credentials securely: Once generated, store your API ID and API Secret in a secure location. Avoid hardcoding them directly into your application code. Recommended practices include using environment variables, configuration files, or a secrets management service.

For detailed, step-by-step instructions with screenshots, refer to the Censys documentation on getting started with the API.

Authenticated request example

This example demonstrates how to make an authenticated request to the Censys API using cURL and the Python SDK. We will query the Censys Search API to retrieve information about a specific host.

cURL Example

For cURL, your API ID and Secret are passed as headers. Replace YOUR_CENSYS_API_ID and YOUR_CENSYS_API_SECRET with your actual credentials.

curl -X GET \
  "https://search.censys.io/api/v2/hosts/1.1.1.1" \
  -H "accept: application/json" \
  -H "Censys-Api-Id: YOUR_CENSYS_API_ID" \
  -H "Censys-Api-Secret: YOUR_CENSYS_API_SECRET"

Python SDK Example

The Python SDK simplifies the process by allowing you to configure your credentials once. Ensure you have the censys-python library installed (pip install censys-python). Best practice dictates loading your API ID and secret from environment variables.

import os
from censys import CensysSearch

# It's recommended to set your API_ID and API_SECRET as environment variables
# For example: export CENSYS_API_ID="YOUR_CENSYS_API_ID"
#              export CENSYS_API_SECRET="YOUR_CENSYS_API_SECRET"

censys_api_id = os.getenv("CENSYS_API_ID")
censys_api_secret = os.getenv("CENSYS_API_SECRET")

if not censys_api_id or not censys_api_secret:
    raise ValueError("Censys API ID and Secret must be set as environment variables.")

s = CensysSearch(api_id=censys_api_id, api_secret=censys_api_secret)

try:
    host_data = s.get_host("1.1.1.1")
    print("Host data for 1.1.1.1:")
    print(host_data)
except Exception as e:
    print(f"An error occurred: {e}")

For more examples and detailed usage of the Python SDK, refer to the Censys Python SDK documentation.

Security best practices

Securing your Censys API credentials is paramount to maintaining the integrity and confidentiality of your data and preventing unauthorized access to your account. Adhere to the following best practices:

• Do not hardcode credentials: Never embed your API ID or API Secret directly into your source code. This is a common vulnerability that can lead to credentials being exposed if the code repository becomes public or is compromised.
• Use environment variables: Store your API ID and API Secret as environment variables on your server or development machine. This isolates credentials from your codebase. For example, in a Unix-like environment: export CENSYS_API_ID="your_id" and export CENSYS_API_SECRET="your_secret". This method is widely accepted for managing sensitive information in development and production environments, as described by Google Cloud security best practices.
• Implement secrets management: For production environments, consider using a dedicated secrets management service such as AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or HashiCorp Vault. These services provide secure storage, retrieval, and rotation of credentials.
• Restrict access to credentials: Ensure that only authorized personnel and systems have access to your API keys. Implement strict access controls on any system where credentials are stored.
• Rotate API keys regularly: Periodically rotate your API keys. If a key is compromised, frequent rotation limits the window of exposure. Censys provides mechanisms within its account settings to revoke old keys and generate new ones.
• Monitor API key usage: Regularly review the activity logs associated with your API keys. Look for unusual patterns or suspicious requests that might indicate a compromise.
• Use principle of least privilege: If Censys introduces role-based access control for API keys in the future, configure keys with the minimum necessary permissions required for their intended function.
• Secure your development environment: Ensure your local development machine and any CI/CD pipelines are secure and free from malware that could capture credentials.
• Encrypt configuration files: If you must store credentials in configuration files, ensure these files are encrypted at rest and their access is restricted.

By following these guidelines, you can significantly reduce the risk of unauthorized access to your Censys account and maintain a secure integration with the Censys API.