How do I get my Shodan API key?

You can obtain your Shodan API key by logging into your Shodan account dashboard. The key is typically displayed prominently on the main account page after successful login. You must first register for a Shodan account if you don't have one.

Can I use OAuth 2.0 with Shodan?

Shodan primarily uses API key authentication for direct programmatic access. While OAuth 2.0 is a common protocol for delegated authorization, Shodan's API is designed for direct application-to-server interaction using a single API key tied to your account.

Is it safe to put my Shodan API key in my code?

No, it is not safe to hardcode your Shodan API key directly into your application's source code. This practice exposes your key to anyone who can view your code. Instead, store it in environment variables or use a secret management service.

What happens if my Shodan API key is compromised?

If your Shodan API key is compromised, an unauthorized party could use your API credits, access your Shodan data, and potentially perform searches or scans under your account. You should immediately generate a new key if Shodan offers that functionality, or contact Shodan support for assistance.

Does Shodan support API key rotation?

The Shodan account dashboard typically displays a single API key associated with your account. While there isn't a direct 'rotate' button in the dashboard, you can contact Shodan support if you need to invalidate an existing key and obtain a new one due to a suspected compromise.

Are there different types of Shodan API keys?

Shodan provides a single API key per user account. The capabilities and credit limits associated with that key depend on your Shodan subscription level (e.g., free, freelancer, academic, corporate), not on different key types.

How do I secure my API key in a Python application?

In Python, the most common and secure method is to store your API key in an environment variable (e.g., SHODAN_API_KEY) and retrieve it using `os.environ.get('SHODAN_API_KEY')` within your application. This prevents the key from being committed to version control.

Shodan Authentication: API Key Setup & Security (2026)

Authentication overview

Shodan's API provides programmatic access to its database of internet-connected devices, enabling developers and researchers to integrate Shodan's capabilities into their applications and workflows. Authentication for the Shodan API is primarily handled through the use of API keys. An API key acts as a unique identifier and secret token that authenticates requests sent to the Shodan API, linking them to a specific user account and its associated access privileges and credit limits.

The Shodan API key is a string of alphanumeric characters that must be included with every API request. This key grants the holder the same access to Shodan's services as the associated user account, including search queries, data exports, and scan functionalities. Therefore, safeguarding your API key is critical to prevent unauthorized access to your Shodan account and potential misuse of your allocated credits.

Shodan provides comprehensive documentation for its API, detailing various endpoints and parameters. The choice of authentication method, specifically the API key, simplifies integration for developers by avoiding more complex protocols like OAuth 2.0 for direct API access, while still requiring careful handling of credentials. For developers working with Shodan, understanding the security implications of API keys and implementing best practices for their management is as important as understanding the API itself.

Supported authentication methods

Shodan primarily supports API key authentication for accessing its services programmatically. This method is straightforward and widely adopted for direct server-to-server or application-to-server communication where a specific user account's privileges need to be asserted. The API key is passed as a parameter in the request URL or as a header, depending on the specific API endpoint and client library used.

API Key Authentication

The Shodan API key is a unique, secret token that authenticates your requests. It is directly tied to your Shodan account and its associated subscription level, determining the features and credit limits available to you. When making a request to a Shodan API endpoint, this key must be included to verify your identity and authorization.

When to use API Keys:

Server-side applications: Ideal for backend services, scripts, or automated tools that interact with the Shodan API without direct user intervention.
Command-line tools: Convenient for quick queries or integrations from a terminal.
Private applications: Suitable for applications where the API key can be securely stored and managed, away from client-side exposure.

Security Considerations for API Keys:

While API keys offer simplicity, they also present security risks if not managed correctly. Unlike OAuth 2.0, which delegates limited access without exposing user credentials directly, an API key often grants broad access to the associated account's capabilities. Therefore, it is crucial to treat API keys as sensitive credentials.

The IETF RFC 6750, while specific to Bearer Tokens, outlines general principles for token security, emphasizing that such tokens should be protected from disclosure and used over secure channels (HTTPS). Similarly, the OAuth 2.0 Client Credentials Grant flow offers a more robust method for machine-to-machine authentication in scenarios requiring higher security or rotation of credentials, though Shodan's direct API key approach streamlines access for many use cases.

The following table summarizes the primary authentication method for Shodan:

Method	When to Use	Security Level
API Key	Server-side applications, scripts, internal tools, direct API access where key can be secured.	Medium (requires careful key management to prevent exposure)

Getting your credentials

To interact with the Shodan API, you will need to obtain an API key from your Shodan account. This key is unique to your account and acts as your primary credential for all API interactions.

Steps to obtain your Shodan API key:

Create a Shodan Account: If you don't already have one, register for a Shodan account on the Shodan registration page. A free account provides limited API access, while paid plans offer higher credit limits and additional features, as detailed on the Shodan pricing page.
Log In: Navigate to the Shodan login page and log in with your credentials.
Access Your API Key: Once logged in, your API key will be prominently displayed on your account dashboard. It's usually labeled as "API Key" or "Your API Key".
Copy Your Key: Copy the displayed API key. This is the value you will use in your API requests.

It is important to note that your API key should be treated as a sensitive password. Do not hardcode it directly into your application's source code, commit it to version control systems like Git, or expose it in client-side code where it could be intercepted. Instead, use environment variables, secret management services, or configuration files that are not publicly accessible.

Authenticated request example

This example demonstrates how to make an authenticated request to the Shodan API using Python, one of the primary languages supported by Shodan's SDKs. The Shodan Python library simplifies API interactions.

Python Example using the Shodan SDK

First, ensure you have the Shodan Python library installed:

pip install shodan

Next, you can make an authenticated request. This example queries Shodan for devices running Nginx.

import shodan
import os

# It's best practice to store your API key in an environment variable
# For example: export SHODAN_API_KEY='YOUR_API_KEY_HERE'
API_KEY = os.environ.get('SHODAN_API_KEY')

if not API_KEY:
    print("Error: SHODAN_API_KEY environment variable not set.")
    print("Please set it using: export SHODAN_API_KEY='YOUR_API_KEY_HERE'")
    exit(1)

try:
    # Setup the API connection
    api = shodan.Shodan(API_KEY)

    # Perform a search query
    # This example searches for devices running Nginx
    results = api.search('nginx')

    print(f'Total results found: {results["total"]}')
    for result in results['matches']:
        print(f'IP: {result["ip_str"]}')
        print(f'Organization: {result.get("org", "N/A")}')
        print(f'Port: {result["port"]}')
        print('---')

except shodan.APIError as e:
    print(f'Error: {e}')

In this example:

The API key is retrieved from an environment variable (SHODAN_API_KEY). This is a crucial security practice.
An instance of shodan.Shodan is created, passing the API key for authentication.
The api.search() method is called, which internally handles the authentication using the provided key.
Error handling is included to catch potential shodan.APIError exceptions, such as an invalid API key or rate limit issues.

For more detailed examples across different programming languages and API endpoints, refer to the Shodan developer documentation and the Shodan API reference.

Security best practices

Securing your Shodan API key is paramount to protect your account, prevent unauthorized usage of your credits, and maintain the integrity of your applications. Adhering to established security best practices for API key management is essential.

1. Do Not Hardcode API Keys

Never embed your API key directly into your source code. Hardcoding keys makes them visible to anyone with access to your codebase, including version control systems. This is a common vulnerability that can lead to key compromise.

2. Use Environment Variables

Store your API key in environment variables. This method keeps the key separate from your codebase and allows you to configure it differently across various deployment environments (development, staging, production). Most programming languages and frameworks provide straightforward ways to access environment variables.

export SHODAN_API_KEY="YOUR_API_KEY_HERE"

3. Utilize Secret Management Services

For production environments, consider using dedicated secret management services like AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or HashiCorp Vault. These services provide secure storage, retrieval, and rotation of API keys and other sensitive credentials, often integrating with your CI/CD pipelines and application runtime environments.

4. Restrict Access and Permissions

Limit who has access to your API keys. In team environments, ensure that only necessary personnel can retrieve or manage production API keys. Implement role-based access control (RBAC) where possible to enforce least privilege principles.

5. Use HTTPS for All API Calls

Always ensure that all communication with the Shodan API occurs over HTTPS. The Shodan API inherently enforces HTTPS, encrypting data in transit and protecting your API key from interception by eavesdroppers during transmission. Using HTTP would expose your key in plain text, making it vulnerable to man-in-the-middle attacks.

6. Implement Rate Limiting and Error Handling

While not directly an authentication security measure, robust error handling and respecting API rate limits (which are tied to your authenticated account) are crucial for application stability and preventing unintended over-usage of your credits. Shodan's API documentation details specific rate limits for different account types.

7. Monitor API Key Usage

Regularly review your Shodan account's API usage statistics. Unusual spikes in activity or requests from unexpected locations could indicate a compromised key. Although Shodan does not currently offer direct key rotation from the dashboard, monitoring usage can help you detect and respond to potential issues promptly.

8. Secure Your Development Environment

Ensure that your local development environment and any machines accessing API keys are secure. This includes using strong passwords, keeping operating systems and software updated, and employing endpoint security solutions.

By following these best practices, you can significantly reduce the risk of your Shodan API key being compromised and maintain a secure interaction with the Shodan platform.