URLScan.io Authentication: API Key Access and Security (2026)

Authentication overview

URLScan.io provides a service for analyzing websites and identifying potential threats, phishing attempts, and malware. Programmatic access to this service, including submitting URLs for analysis and retrieving detailed reports, is managed through its API. Authentication for the URLScan.io API is primarily handled via API keys, which serve as a unique identifier and secret token for users and their applications.

When an authenticated request is made to the URLScan.io API, the provided API key is used to verify the sender's identity and determine their authorization level. This mechanism ensures that only legitimate users can access the service and perform actions corresponding to their account's capabilities, such as the number of scans allowed per day or access to private scanning features, as detailed in the URLScan.io pricing tiers. The API design follows RESTful principles, making it accessible with standard HTTP clients and various programming languages.

Supported authentication methods

URLScan.io's API utilizes a single, consistent method for authentication: API keys. This approach simplifies integration for developers while providing a clear method for access control.

API keys are typically passed in an HTTP header named API-Key. This method is a common practice for authenticating API requests, as described in various HTTP authentication specifications. The API key acts as a bearer token, granting access to the bearer without further challenge once verified by the server.

Getting your credentials

To obtain an API key for URLScan.io, you must have a registered account on the platform. The process involves generating a key through the user interface:

1. Create an Account: Navigate to the URLScan.io homepage and register for a new account if you do not already have one. The free tier allows for 50 public scans per day, which is suitable for non-commercial use.
2. Access User Settings: Log in to your URLScan.io account. Once logged in, locate and click on your username or account icon, usually in the top right corner, to access your user settings or profile page.
3. Generate API Key: Within your user settings, there will be a section dedicated to API keys. This section typically provides an option to generate a new API key. Follow the on-screen prompts to create a new key.
4. Securely Store 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, URLScan.io typically only displays the key once upon generation and does not allow retrieval afterward. If a key is lost, it must be revoked and a new one generated.
5. Review Daily Limits: Be aware that the type of account (free or paid) dictates your daily scan limits and access to features like private scans. These limits are enforced via your API key. For details on different tiers, refer to the URLScan.io documentation.

It is advisable to generate separate API keys for different applications or environments (e.g., development, staging, production) to facilitate easier key rotation and revocation if a key is compromised.

Authenticated request example

After obtaining your API key, you can use it to make authenticated requests to the URLScan.io API. The key is typically included in the API-Key HTTP header. Below are examples using curl and Python, demonstrating how to submit a URL for scanning.

cURL Example

To submit a URL for a public scan using curl, replace YOUR_API_KEY with your actual API key and https://example.com with the URL you wish to scan.

curl -X POST 'https://urlscan.io/api/v1/scan/' \
  -H 'API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "visibility": "public"}'

This command sends a POST request to the /api/v1/scan/ endpoint, including the API key in the header and the target URL in the JSON body, with "visibility": "public" specifying a public scan.

Python Example

Using the Python requests library, an authenticated scan submission would look like this:

import requests
import json

api_key = "YOUR_API_KEY"
url_to_scan = "https://example.com"

headers = {
    'API-Key': api_key,
    'Content-Type': 'application/json'
}

payload = {
    'url': url_to_scan,
    'visibility': 'public' # or 'unlisted', 'private' for paid tiers
}

response = requests.post('https://urlscan.io/api/v1/scan/', headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    print("Scan initiated successfully!")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.json())

This Python script constructs the necessary headers and payload, then sends the POST request. The response contains details about the initiated scan, including its UUID, which can be used to fetch results later from the URLScan.io API reference.

Security best practices

Securing your URLScan.io API keys is crucial to prevent unauthorized access to your account and potential misuse of your scanning quotas. Adhering to general API key security principles, as outlined by providers like Google's API key best practices, is highly recommended.

• Treat API Keys as Sensitive Credentials: Your API key grants access to your URLScan.io account. Treat it with the same level of security as you would a password or private cryptographic key.
• Do Not Embed Keys Directly in Code: Avoid hardcoding API keys directly into your application's source code. This practice risks exposure if the code is publicly shared or compromised.
• Use Environment Variables: Store API keys in environment variables, configuration files that are not committed to version control, or secure secret management services. This keeps keys separate from your codebase.
• Implement Least Privilege: While URLScan.io API keys currently have broad access to your account's capabilities, be mindful of where and how you use them. If URLScan.io were to introduce more granular permissions in the future, apply the principle of least privilege.
• Regularly Rotate Keys: Periodically generate new API keys and revoke old ones. This practice reduces the window of opportunity for a compromised key to be exploited.
• Monitor Usage: Regularly check your URLScan.io account for unusual activity or excessive API calls that might indicate unauthorized use of your key.
• Secure Your Development Environment: Ensure that your development machines and build pipelines are secure to prevent key exfiltration during development or deployment.
• Avoid Public Exposure: Never expose your API key in client-side code, public repositories, or unsecured logs. If a key is accidentally exposed, revoke it immediately through your URLScan.io account settings and generate a new one.
• Use HTTPS: All communication with the URLScan.io API should occur over HTTPS to encrypt data in transit, protecting your API key from interception.

By following these best practices, you can significantly enhance the security posture of your integrations with the URLScan.io API.