Authentication overview

The Clearbit API utilizes a straightforward authentication model centered on API keys. An API key acts as a unique identifier and secret token that your application sends with each request to the Clearbit API. This key verifies your identity and authorization to access Clearbit's various data enrichment services, such as Clearbit Reveal or Person and Company Enrichment. The use of API keys is a common practice for accessing web services, providing a balance between security and ease of implementation for developers as described by Google Cloud.

When you make an authenticated request, the API key is transmitted over a secure connection (HTTPS/TLS) to prevent eavesdropping and tampering. Clearbit's infrastructure then validates the provided key against its records to ensure it is active and associated with an authorized account. Successful validation grants your application access to the requested data, while an invalid or missing key will result in an authentication error, typically an HTTP 401 Unauthorized status.

Understanding the proper handling of these keys is fundamental to integrating with Clearbit securely. This includes keeping keys confidential, rotating them periodically, and restricting their scope where possible. The Clearbit developer dashboard provides tools for managing your API keys, including creation, revocation, and monitoring of usage.

Supported authentication methods

Clearbit API primarily supports one authentication method for programmatic access: a secret API key. This key is passed in the HTTP request header as a Bearer token.

API Key (Bearer Token)

This is the standard and recommended method for authenticating with the Clearbit API. Your unique API key is a long, randomly generated string that you obtain from your Clearbit account dashboard. When making an API request, you include this key in the Authorization HTTP header, prefixed with Bearer. This method is widely used across various APIs due to its simplicity and effectiveness for client-server communication.

How it works:

  1. You generate a secret API key from your Clearbit account.
  2. For each API request, you include the header: Authorization: Bearer YOUR_API_KEY.
  3. The Clearbit API server validates the key before processing the request.

This approach ensures that all requests originating from your application are identified and authorized, linking them to your Clearbit account and associated usage limits and permissions. The use of HTTPS is mandatory for all API calls to protect the transmission of your API key from interception.

The following table summarizes the primary authentication method:

Method When to Use Security Level
API Key (Bearer Token) All server-side and trusted client-side applications interacting directly with Clearbit API. High (when properly managed and transmitted over HTTPS).

Getting your credentials

To begin using the Clearbit API, you will need to obtain your API key from your Clearbit account. This process typically involves a few steps within the Clearbit developer dashboard, which centralizes key management and provides insights into API usage.

Step-by-step guide to retrieving your API key:

  1. Sign up or Log in: Navigate to the Clearbit website and either sign up for a new account or log in to your existing one.
  2. Access Dashboard: Once logged in, locate and access your developer dashboard or account settings. The exact navigation might vary but often includes sections like "API Keys", "Settings", or "Integrations". For specific instructions, refer to the official Clearbit documentation.
  3. Generate or Locate API Key: Within the API Key section, you will typically find an option to generate a new API key if you don't have one already, or view your existing active keys. Clearbit usually provides a single primary secret API key for your account.
  4. Copy Your Key: Carefully copy your API key. It is crucial to treat this key as a sensitive credential, similar to a password. Do not hardcode it directly into client-side code that is publicly accessible, and avoid sharing it unnecessarily.
  5. Environment Variables (Recommended): For server-side applications, store your API key in an environment variable rather than directly in your source code. This practice helps prevent accidental exposure of your key, especially if your codebase is version-controlled.

Clearbit's dashboard also provides features for revoking compromised keys and generating new ones, which is an important security measure. Regularly reviewing your active keys and their usage can help maintain the security of your integration.

Authenticated request example

Once you have obtained your Clearbit API key, you can use it to make authenticated requests to any of the Clearbit API endpoints. The following examples demonstrate how to include your API key as a Bearer token in the Authorization header using common programming languages. Replace YOUR_API_KEY with your actual Clearbit API key.

Example in Node.js (using fetch or axios)


const fetch = require('node-fetch'); // Or use axios

const API_KEY = process.env.CLEARBIT_API_KEY; // Store in environment variable
const email = '[email protected]';

async function enrichPerson(email) {
  try {
    const response = await fetch(`https://person.clearbit.com/v2/people/find?email=${email}`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });

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

    const data = await response.json();
    console.log('Enriched Person Data:', data);
  } catch (error) {
    console.error('Error enriching person:', error);
  }
}

enrichPerson(email);

Example in Python (using requests library)


import os
import requests

API_KEY = os.environ.get('CLEARBIT_API_KEY') # Store in environment variable
email = '[email protected]'

def enrich_person(email):
    if not API_KEY:
        print("Error: CLEARBIT_API_KEY environment variable not set.")
        return

    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    params = {
        'email': email
    }

    try:
        response = requests.get('https://person.clearbit.com/v2/people/find', headers=headers, params=params)
        response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)
        data = response.json()
        print("Enriched Person Data:", data)
    except requests.exceptions.RequestException as e:
        print(f"Error enriching person: {e}")

enrich_person(email)

Example in Ruby (using Net::HTTP)


require 'net/http'
require 'uri'
require 'json'

API_KEY = ENV['CLEARBIT_API_KEY'] # Store in environment variable
email = '[email protected]'

def enrich_person(email)
  if API_KEY.nil?
    puts "Error: CLEARBIT_API_KEY environment variable not set."
    return
  end

  uri = URI("https://person.clearbit.com/v2/people/find?email=#{email}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true # Enable SSL/TLS

  request = Net::HTTP::Get.new(uri.request_uri)
  request['Authorization'] = "Bearer #{API_KEY}"
  request['Content-Type'] = 'application/json'

  response = http.request(request)

  if response.is_a?(Net::HTTPSuccess)
    puts "Enriched Person Data: #{JSON.parse(response.body)}"
  else
    puts "Error enriching person: #{response.code} #{response.message}"
    puts response.body
  end
end

enrich_person(email)

These examples illustrate the general pattern for including your API key. Clearbit also provides official SDKs for JavaScript, Ruby, Python, Node.js, PHP, and Go, which often abstract away the direct handling of HTTP headers and simplify the process of making authenticated requests.

Security best practices

Securing your Clearbit API integration involves protecting your API key and ensuring that your data exchanges are confidential and integral. Adhering to established security practices is crucial for preventing unauthorized access and maintaining compliance.

API Key Management

  • Keep Keys Confidential: Treat your Clearbit API key as a sensitive password. Never embed it directly in publicly accessible client-side code (e.g., JavaScript in a browser), mobile applications, or commit it directly to public version control repositories like GitHub.
  • Use Environment Variables: For server-side applications, store your API key in environment variables. This prevents the key from being exposed if your source code is compromised or accidentally published.
  • Restrict Access: Limit who in your organization has access to Clearbit API keys. Implement role-based access control (RBAC) if your development environment supports it.
  • Key Rotation: Periodically rotate your API keys. Clearbit's dashboard allows you to revoke old keys and generate new ones. Regular rotation minimizes the risk associated with a long-lived, potentially compromised key.
  • Monitor Usage: Regularly check your Clearbit API usage logs and analytics in your dashboard for any unusual activity that might indicate unauthorized use of your key.

Secure Communication

  • Always Use HTTPS: All communication with the Clearbit API must occur over HTTPS (HTTP Secure). This encrypts the data exchanged, including your API key, protecting it from interception during transit. Clearbit API endpoints enforce HTTPS, and requests over HTTP will fail.
  • TLS Best Practices: Ensure your application uses up-to-date TLS (Transport Layer Security) versions and strong cipher suites. Older TLS versions (e.g., TLS 1.0, 1.1) have known vulnerabilities as detailed by MDN Web Docs.

Error Handling and Logging

  • Handle Authentication Errors Gracefully: Implement robust error handling for 401 Unauthorized responses. This allows your application to respond appropriately without exposing sensitive information or crashing.
  • Avoid Logging Sensitive Data: Be cautious about what information is logged. Never log your raw API key or other sensitive credentials in application logs, especially in production environments. Mask or redact such information if logging is necessary for debugging.

Client-Side Considerations (if applicable)

While Clearbit API keys are generally intended for server-side use, if you have a specific use case requiring client-side integration (e.g., for forms or dynamic content), ensure that you use a proxy server. A proxy server can securely hold your API key and forward requests to Clearbit on behalf of the client, adding an extra layer of security. This prevents direct exposure of the API key in the browser.