Phisherman Authentication: API Key Setup & Security (2026)

Authentication overview

Phisherman employs API key authentication to control access to its phishing link detection services. API keys serve as long-lived tokens that identify the calling application or user and authorize their requests against the Phisherman API. This method is common for web services requiring straightforward authorization without complex user consent flows, as detailed in the Phisherman documentation. Each API key is associated with a specific user account and its corresponding usage plan, allowing Phisherman to track API consumption and enforce rate limits.

The API key must be transmitted securely with every API request. Phisherman's API endpoints are exclusively served over HTTPS, which encrypts communications between your application and the API server, protecting the API key from interception during transit. This adherence to HTTPS/TLS is a standard security practice for web APIs, as recommended by security guidelines for Transport Layer Security (TLS).

While API keys offer simplicity, their security relies heavily on proper management and storage within your application environment. Unlike more dynamic authentication methods like OAuth 2.0, API keys typically do not expire automatically and grant direct access to API functions. Therefore, safeguarding your API keys is crucial to prevent unauthorized access and potential misuse of your allocated API lookups.

Supported authentication methods

Phisherman primarily supports API key authentication for accessing its services. This method involves including a unique, secret key with each request to verify the identity of the caller.

The API key is a string that your application sends with each request. For Phisherman, this key is typically passed in a custom HTTP header or as a query parameter, depending on the specific API endpoint and SDK implementation. The Phisherman API reference provides detailed instructions on where to place the API key for different endpoints.

Getting your credentials

To obtain an API key for Phisherman, you must first create an account on their platform. Once registered and logged in, your API key will be accessible through your user dashboard.

1. Create a Phisherman Account: Navigate to the Phisherman homepage and sign up for a new account.
2. Access the Dashboard: After successful registration and login, you will be redirected to your personal Phisherman dashboard.
3. Locate API Key Section: Within the dashboard, look for a section labeled "API Keys" or similar. This section typically displays your generated key.
4. Generate/Copy API Key: If a key is not automatically displayed, there might be an option to "Generate New API Key." Once generated, copy the key. This key is your secret credential; treat it with the same care as a password.

Phisherman's free tier provides a generous allowance of 100 API lookups per minute and 100,000 lookups per month, making it suitable for getting started. Paid plans, starting at $5/month, scale with lookup volume and offer higher rate limits if your application requires more extensive usage, as outlined on the Phisherman pricing page.

Authenticated request example

When making requests to the Phisherman API, your API key needs to be included in the Authorization header using the Bearer scheme. This is a common and recommended practice for API key transmission, providing a clear and standard way to present credentials, as documented by RFC 6750 for Bearer Token Usage.

Node.js Example (using axios)

const axios = require('axios');

const PHISHERMAN_API_KEY = 'YOUR_PHISHERMAN_API_KEY'; // Replace with your actual API key
const PHISHERMAN_API_ENDPOINT = 'https://api.phisherman.gg/v2/scam/check';

async function checkUrl(url) {
  try {
    const response = await axios.post(
      PHISHERMAN_API_ENDPOINT,
      { url: url },
      {
        headers: {
          'Authorization': `Bearer ${PHISHERMAN_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log(`Checking URL: ${url}`);
    console.log('Phisherman response:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error checking URL with Phisherman:', error.response ? error.response.data : error.message);
    throw error;
  }
}

// Example usage:
checkUrl('https://example-phishing-site.com').then(result => {
  // Process result
});

Python Example (using requests)

import requests

PHISHERMAN_API_KEY = 'YOUR_PHISHERMAN_API_KEY'  # Replace with your actual API key
PHISHERMAN_API_ENDPOINT = 'https://api.phisherman.gg/v2/scam/check'

def check_url(url):
    headers = {
        'Authorization': f'Bearer {PHISHERMAN_API_KEY}',
        'Content-Type': 'application/json'
    }
    payload = {'url': url}
    try:
        response = requests.post(PHISHERMAN_API_ENDPOINT, json=payload, headers=headers)
        response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
        print(f"Checking URL: {url}")
        print('Phisherman response:', response.json())
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error checking URL with Phisherman: {e}")
        if response.content:
            print('Error details:', response.json())
        raise

# Example usage:
# check_url('https://malicious-site.net')

These examples illustrate how to construct an authenticated request using common programming languages and libraries. The key principles are consistent: include your API key in the Authorization header, and ensure all communications are made over HTTPS.

Security best practices

Securing your Phisherman API keys is paramount to prevent unauthorized access, protect your account from exceeding usage limits, and maintain the integrity of your application. Adhering to these best practices will significantly enhance the security posture of your integration:

• Environment Variables: Never hardcode API keys directly into your source code. Instead, store them as environment variables (e.g., PHISHERMAN_API_KEY). This practice keeps sensitive data separate from your codebase, making it easier to manage and less likely to be exposed in version control systems or during deployments. Most modern application frameworks and deployment pipelines support environment variables natively.
• Secret Management Services: For production environments, consider using dedicated secret management services such as AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, or HashiCorp Vault. These services provide secure storage, fine-grained access control, and auditing capabilities for API keys and other sensitive configurations. They rotate keys automatically and inject them into your application at runtime, reducing the risk of a breach.
• Least Privilege: If Phisherman were to offer different types of API keys with varying permissions (e.g., read-only, admin), always use the key with the minimum necessary permissions for your application's function. Phisherman currently uses a single API key type, but this principle applies broadly to all API integrations.
• Restrict Access: Limit who has access to your Phisherman API keys. Only authorized developers and systems should be able to retrieve or view the keys. Implement strong access controls within your organization and development workflows.
• Monitor Usage: Regularly monitor your API key usage through the Phisherman dashboard. Unusual spikes in requests or activity can indicate a compromised key, allowing you to react quickly by revoking the key.
• Key Revocation and Rotation: If you suspect an API key has been compromised, immediately revoke it via your Phisherman dashboard and generate a new one. Periodically rotating API keys (e.g., every 90 days) is also a good security practice, even without a suspected compromise. This limits the window of exposure if a key is inadvertently disclosed.
• HTTPS Enforcement: Always ensure your application communicates with the Phisherman API over HTTPS. Phisherman enforces HTTPS, but it's crucial for your application to explicitly use https:// in all API calls to prevent man-in-the-middle attacks that could intercept your API key.
• Client-Side Security (if applicable): If your API key must be used in client-side code (e.g., in a browser-based application), carefully consider the risks. Publicly exposed keys can be easily extracted. If client-side requests are necessary, consider proxying them through a secure backend that adds the API key, or investigate if Phisherman supports domain restrictions for API keys to limit their use to specific origins.
• Error Handling: Implement robust error handling in your application. Avoid logging API keys or other sensitive information in plain text when errors occur. Ensure that error messages exposed externally do not contain sensitive details.

By implementing these security measures, you can significantly mitigate the risks associated with API key management and ensure the secure and reliable operation of your Phisherman integration.