Authentication overview

Tomba email finder utilizes API keys as its primary method for authenticating requests to its API. This approach is common for RESTful web services, providing a straightforward mechanism for developers to secure access to their accounts programmatically. An API key is a unique identifier that authenticates a user or application when making requests to an API, linking the request to a specific Tomba account and its associated usage limits and permissions.

The Tomba API is designed as a RESTful service, meaning it uses standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources. Authentication with an API key typically involves including the key in each API request, either within the request headers or as a query parameter. This allows the Tomba API backend to verify the identity of the caller before processing the request and returning data such as email addresses or verification statuses.

Integrating API key authentication requires careful handling of the key to prevent unauthorized access. Best practices include storing keys securely and transmitting them over encrypted channels. Tomba offers a comprehensive API reference that details how to implement authentication across various endpoints, including those for finding emails, verifying email addresses, and performing domain searches.

Supported authentication methods

Tomba email finder exclusively supports API key authentication for its public API. This method is a widely adopted practice for securing access to web services due to its simplicity and effectiveness in many use cases. Unlike more complex schemes such as OAuth 2.0, API key authentication does not involve token exchange flows or refresh tokens; instead, a persistent key acts as the credential.

When an API key is generated, it serves as a secret that identifies the calling application or user. The security of this method largely depends on the confidentiality of the API key itself. If an API key is compromised, an unauthorized entity could impersonate the legitimate user, consuming their API quota or potentially accessing sensitive information, depending on the scope of the API.

For scenarios requiring more granular control over user permissions or third-party application access without exposing user credentials, other authentication methods like OAuth 2.0 might be considered. However, for direct application-to-service communication where a single application needs access to its own account's resources, API keys are a suitable and efficient choice, as documented by organizations like Google for their own developer APIs.

Method When to Use Security Level
API Key Direct application-to-service communication; when a single application requires access to its own resources. Moderate (depends heavily on key management practices)

Getting your credentials

To obtain your Tomba email finder API key, you must first have an active Tomba account. Once registered and logged in, the API key can be generated and managed directly from your user dashboard. The process generally involves navigating to a dedicated API settings or developer section within your account.

  1. Create an Account: If you don't already have one, sign up for a Tomba account on their official website. Tomba offers a free tier that includes a limited number of search requests and verifications per month, which can be used for initial API testing.
  2. Access Dashboard: Log in to your Tomba account.
  3. Navigate to API Settings: Look for a section labeled "API", "Developers", or "Settings > API Key" within your dashboard interface. The exact path may vary, but it is typically clear and accessible. Refer to the Tomba API reference for specific navigation instructions.
  4. Generate Key: Within the API settings, you'll find an option to generate a new API key. Tomba typically provides a single primary API key for your account. You might also have options to revoke existing keys or regenerate new ones if a key is compromised.
  5. Store Key Securely: Once generated, copy your API key and store it immediately in a secure location. It is crucial to treat this key as a sensitive secret. Tomba's documentation advises against hardcoding API keys directly into client-side code or public repositories.

Remember that your API key is directly tied to your account and its usage limits. Keep it confidential to prevent unauthorized access and usage that could deplete your quota.

Authenticated request example

Once you have obtained your API key, you can use it to authenticate your requests to the Tomba email finder API. The key is typically passed as a query parameter named api_key in the URL, or as an X-Tomba-Key HTTP header. The examples below demonstrate how to make an authenticated request using the api_key query parameter in Python and Node.js.

Python Example

This Python example uses the requests library to perform a domain search, which is one of Tomba's core products.

import requests
import os

# It is recommended to store your API key in an environment variable
API_KEY = os.environ.get("TOMBA_API_KEY")

if not API_KEY:
    raise ValueError("TOMBA_API_KEY environment variable not set.")

DOMAIN = "stripe.com"  # Example domain

url = f"https://api.tomba.io/v1/email-finder/{DOMAIN}"

headers = {
    "User-Agent": "Tomba API Python Client"
}

params = {
    "api_key": API_KEY,
    "query": "john" # Example: search for 'john' at stripe.com
}

try:
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()  # Raise an exception for HTTP errors
    data = response.json()
    print(data)
except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
except Exception as err:
    print(f"An error occurred: {err}")

Node.js Example

This Node.js example uses the node-fetch library (or built-in fetch in newer Node.js versions) to perform an email verification.

import fetch from 'node-fetch'; // For Node.js versions without native fetch

// Store your API key in an environment variable
const API_KEY = process.env.TOMBA_API_KEY;

if (!API_KEY) {
    throw new Error("TOMBA_API_KEY environment variable not set.");
}

const EMAIL_TO_VERIFY = "[email protected]"; // Example email

const url = `https://api.tomba.io/v1/email-verifier/${EMAIL_TO_VERIFY}?api_key=${API_KEY}`;

async function verifyEmail() {
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'User-Agent': 'Tomba API Node.js Client'
            }
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error(`An error occurred: ${error.message}`);
    }
}

verifyEmail();

These examples demonstrate the basic structure for including the API key in your request. For more detailed examples and specific endpoint usage, consult the Tomba API documentation.

Security best practices

Securing your API keys is critical to maintain the integrity of your application and prevent unauthorized use of your Tomba account. Adhering to established security practices minimizes risks associated with credential exposure.

  • Environment Variables: Store your API keys as environment variables on your server or development machine rather than hardcoding them directly into your application's source code. This practice prevents keys from being accidentally committed to version control systems like Git. The Twilio webhook security guide provides further context on using environment variables for sensitive data.
  • Server-Side Storage: If your application is a web application, process all API requests from your backend server. Never expose your API key directly in client-side code (e.g., JavaScript in a web browser or mobile app bundle), as this makes the key easily discoverable by malicious actors.
  • Access Control: Implement strict access controls for anyone who can view or modify your API keys within your team or organization. Limit access to only necessary personnel.
  • IP Whitelisting (if available): Check the Tomba dashboard for features like IP whitelisting. If supported, configure your API key to only accept requests originating from a predefined list of trusted IP addresses. This adds an extra layer of security, as even if a key is stolen, it cannot be used from an unauthorized location.
  • Regular Key Rotation: Periodically rotate your API keys. This involves generating a new key and updating your application to use it, then revoking the old key. Regular rotation mitigates the risk associated with a long-lived, potentially compromised key.
  • Monitor Usage: Regularly monitor your API key's usage through your Tomba dashboard. Unusual spikes in activity or requests from unexpected locations could indicate a compromise.
  • Secure Transmission: Always ensure that all communications with the Tomba API occur over HTTPS. This encrypts the data in transit, protecting your API key and other sensitive information from interception. Most modern HTTP client libraries enforce HTTPS by default.
  • Error Handling: Implement robust error handling in your application to catch and respond to authentication failures gracefully, avoiding the exposure of sensitive details in error messages.

By diligently following these practices, developers can significantly enhance the security posture of their integration with the Tomba email finder API.