SecurityTrails Getting Started: API Access and First Request

Getting started overview

Getting started with the SecurityTrails API involves a sequence of steps to establish access and begin retrieving data. This process typically includes creating an account, locating your API key, and performing an initial authenticated request. The SecurityTrails API provides access to current and historical DNS, WHOIS, and IP data, which can be integrated into various security operations, such as threat intelligence, asset management, and open-source intelligence (OSINT) gathering SecurityTrails API overview. Once configured, developers can query domain and IP information programmatically.

The following table outlines the key steps to initiate API usage:

Create an account and get keys

To begin using the SecurityTrails API, an account is required. SecurityTrails offers various plans, including a limited community access tier SecurityTrails pricing information, which allows basic API usage. Full enterprise access with custom pricing is available for more extensive needs Enterprise pricing details.

Account Creation Process:

1. Navigate to the SecurityTrails pricing page.
2. Select your desired plan, such as the free 'Community Access' or one of the paid tiers.
3. Complete the registration form by providing an email address and creating a password.
4. Verify your email address, if prompted.

Retrieving Your API Key:

Once your account is active, your API key can be found within your account dashboard. This key is essential for authenticating all your API requests and should be kept confidential to prevent unauthorized access to your account and data allowances. API keys function as a form of authentication, similar to how OAuth 2.0 uses tokens for resource access OAuth 2.0 specification overview.

1. Log in to your SecurityTrails account.
2. Navigate to the 'API' section or 'Account Settings' within your dashboard.
3. Locate the displayed API key, which is a unique alphanumeric string.
4. Copy the API key. It will be used in the API_KEY header for subsequent requests.

For security best practices, avoid hardcoding your API key directly into your application code. Instead, use environment variables or a secure configuration management system to store and access it.

Your first request

After obtaining your API key, you can make your first authenticated request. This example demonstrates how to query the current DNS records for a domain. The SecurityTrails API requires the API key to be passed in the API_KEY header of each request.

Example using cURL:

cURL is a command-line tool for making requests over various protocols and is commonly used for interacting with RESTful APIs cURL man page. The following command retrieves the current DNS A records for example.com.

curl -X GET \
  --header "API_KEY: YOUR_API_KEY" \
  "https://api.securitytrails.com/v1/domain/example.com/dns/a"

Replace YOUR_API_KEY with the actual API key copied from your dashboard.

Example using Python:

Python is a widely used language for scripting and web development, and its requests library simplifies HTTP requests Python Requests documentation. This Python example performs the same query as the cURL example.

import requests
import os

# It's recommended to store your API key in an environment variable
api_key = os.environ.get("SECURITYTRAILS_API_KEY")
if not api_key:
    print("Error: SECURITYTRAILS_API_KEY environment variable not set.")
    exit(1)

domain = "example.com"
url = f"https://api.securitytrails.com/v1/domain/{domain}/dns/a"

headers = {
    "API_KEY": api_key
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Before running the Python script, set the environment variable:

export SECURITYTRAILS_API_KEY="YOUR_API_KEY"

Remember to replace YOUR_API_KEY with your actual key.

Common next steps

Once you have successfully made your first API call, consider these next steps to further integrate SecurityTrails into your workflows:

1. Explore the API Reference: Review the comprehensive SecurityTrails API reference to understand the full range of available endpoints. This includes endpoints for domain data, IP data, WHOIS records, historical data, and more. Each endpoint offers specific query parameters to refine your searches.

2. Error Handling: Implement robust error handling in your application. The API returns standard HTTP status codes (e.g., 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error). Understanding these codes and their corresponding JSON error messages will help your application gracefully manage issues SecurityTrails error codes documentation.

3. Rate Limits: Be aware of the API rate limits associated with your account tier. Exceeding these limits will result in 429 Too Many Requests responses. Implement strategies like exponential backoff and request queuing to manage your API call volume effectively SecurityTrails rate limiting policies.

4. Data Parsing and Storage: The API responses are in JSON format. Develop methods to parse this data and extract the information relevant to your needs. For large datasets or ongoing monitoring, consider storing the retrieved data in a database for easier querying and analysis.

5. Automate Workflows: Integrate SecurityTrails data into automated security workflows. This could include enriching SIEM alerts with domain context, automating asset inventory updates, or supporting incident response playbooks with real-time threat intelligence.

6. Explore SDKs (if available): While SecurityTrails primarily provides RESTful API access, check for community-contributed SDKs or libraries that might simplify interaction with the API in your preferred programming language. At the time of writing, official SDKs are not listed, but HTTP client libraries are common SecurityTrails official documentation.

Troubleshooting the first call

Encountering issues with your initial API request can be frustrating. Here are common problems and their solutions:

• 401 Unauthorized: Invalid API Key
  • Cause: The API key provided is missing, incorrect, or expired.
  • Solution: Double-check that you have copied the correct API key from your SecurityTrails dashboard API settings. Ensure there are no leading or trailing spaces. Confirm the key is passed in the API_KEY header as specified.
• 400 Bad Request: Malformed Request or Invalid Parameters
  • Cause: The request URL is incorrect, or required parameters are missing or malformed.
  • Solution: Review the SecurityTrails API reference for the specific endpoint you are calling. Ensure the URL structure, path parameters (like the domain name), and query parameters (if any) match the documentation precisely. Confirm data types for parameters.
• 404 Not Found: Endpoint or Resource Not Found
  • Cause: The endpoint URL is incorrect, or the requested resource (e.g., domain) does not exist or has no data.
  • Solution: Verify the endpoint path against the API documentation. For domain-specific requests, confirm the domain name is spelled correctly and is accessible via SecurityTrails.
• 429 Too Many Requests: Rate Limit Exceeded
  • Cause: You have sent too many requests within a given timeframe, exceeding your plan's rate limit.
  • Solution: Wait for the rate limit window to reset. Implement proper rate-limiting handling in your code, such as exponential backoff, to avoid hitting limits repeatedly. Consider upgrading your plan if higher throughput is consistently needed SecurityTrails pricing tiers.
• Network Connectivity Issues
  • Cause: Your client cannot reach the SecurityTrails API servers due to local network problems, firewall restrictions, or DNS issues.
  • Solution: Check your internet connection. Ensure no local firewalls or proxies are blocking outgoing HTTPS requests to api.securitytrails.com. Try performing a simple ping api.securitytrails.com or traceroute api.securitytrails.com to diagnose network path issues.