Checkr Authentication: API Security & Credential Management

Authentication overview

Checkr's API utilizes API keys as the primary mechanism for authenticating client applications. This approach allows developers to integrate Checkr's background check services into their platforms securely. When an API key is included in a request, Checkr verifies the key against its records to confirm the sender's authorization to access the requested resources and perform specified actions, such as initiating background checks or retrieving report statuses. This authentication process is fundamental for maintaining the security and privacy of sensitive candidate data, adhering to compliance standards like FCRA, SOC 2 Type II, GDPR, and CCPA.

In addition to API keys for outgoing requests, Checkr implements webhook signatures for authenticating incoming notifications. Webhooks deliver real-time updates on the status of background checks to a specified endpoint. To ensure the integrity and authenticity of these notifications, each webhook payload is accompanied by a signature. This signature allows the receiving application to verify that the webhook originated from Checkr and that its content has not been tampered with during transit, providing an additional layer of security for asynchronous communication.

Supported authentication methods

Checkr supports API key-based authentication for its RESTful API. This method is common for server-to-server communication and is well-suited for applications that need to programmatically interact with Checkr's services, such as initiating background checks, retrieving report details, or managing candidate information. The API keys provided by Checkr are designed to grant specific permissions, depending on the key type generated.

For securing webhook payloads, Checkr uses HMAC-SHA256 signatures. This cryptographic hash function ensures that webhook notifications received by your application are genuinely from Checkr and have not been altered. Verifying these signatures is a critical step in building secure and reliable integrations that depend on real-time updates from Checkr.

Getting your credentials

To begin authenticating with Checkr's API, you will need to obtain API keys from your Checkr dashboard. Checkr provides two main types of API keys for developers: a publishable key and a secret key. While the publishable key is mentioned, it is typically used for client-side integrations if any, and the secret key is what you will primarily use for server-side API calls. For detailed instructions, refer to the official Checkr authentication documentation.

1. Access your Checkr Dashboard: Log in to your Checkr account.
2. Navigate to API Settings: Look for a section related to 'Developer Settings' or 'API Keys' within the dashboard. The exact path may vary but is typically found under 'Account Settings' or a similar administrative menu.
3. Generate API Keys: Within the API settings, you will find options to view or generate your API keys. Checkr provides both a Test API Key for usage within their sandbox environment and a Live API Key for production environments. Ensure you use the correct key for your current development phase. The secret key is the one required for authenticating server-side requests.
4. Webhook Signing Secret: If you plan to use webhooks to receive real-time updates, you will also find a webhook signing secret in the same API settings section. This secret is crucial for verifying the authenticity of incoming webhook notifications.

It is critical to treat your secret API keys and webhook signing secrets as sensitive credentials. Never hardcode them directly into your application's source code or expose them in client-side code. Instead, use environment variables or a secure secret management service for storage and retrieval. This practice significantly reduces the risk of unauthorized access to your Checkr account.

Authenticated request example

Checkr's API expects the secret API key to be sent in the Authorization header of your HTTP requests as a Bearer token. The following examples demonstrate how to make an authenticated request using popular programming languages. These examples assume you have stored your secret API key securely, for instance, in an environment variable named CHECKR_API_KEY.

Node.js

const axios = require('axios');

const checkrApiKey = process.env.CHECKR_API_KEY; // Ensure this is set securely

async function createCandidate() {
  try {
    const response = await axios.post(
      'https://api.checkr.com/v1/candidates',
      {
        first_name: 'John',
        last_name: 'Doe',
        email: '[email protected]'
      },
      {
        headers: {
          'Authorization': `Bearer ${checkrApiKey}`,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Candidate created:', response.data);
  } catch (error) {
    console.error('Error creating candidate:', error.response ? error.response.data : error.message);
  }
}

createCandidate();

Python

import os
import requests

checkr_api_key = os.environ.get('CHECKR_API_KEY') # Ensure this is set securely

def create_candidate():
    url = "https://api.checkr.com/v1/candidates"
    headers = {
        "Authorization": f"Bearer {checkr_api_key}",
        "Content-Type": "application/json"
    }
    payload = {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]"
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status() # Raise an exception for HTTP errors
        print("Candidate created:", response.json())
    except requests.exceptions.RequestException as e:
        print(f"Error creating candidate: {e}")

create_candidate()

Ruby

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

CHECKR_API_KEY = ENV['CHECKR_API_KEY'] # Ensure this is set securely

def create_candidate
  uri = URI.parse('https://api.checkr.com/v1/candidates')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.request_uri)
  request['Authorization'] = "Bearer #{CHECKR_API_KEY}"
  request['Content-Type'] = 'application/json'
  request.body = { first_name: 'Robert', last_name: 'Johnson', email: '[email protected]' }.to_json

  response = http.request(request)

  if response.is_a?(Net::HTTPSuccess)
    puts "Candidate created: #{JSON.parse(response.body)}"
  else
    puts "Error creating candidate: #{response.code} - #{response.body}"
  end
rescue StandardError => e
  puts "An error occurred: #{e.message}"
end

create_candidate

Security best practices

Implementing strong security practices when integrating with Checkr's authentication mechanisms is paramount due to the sensitive nature of background check data. Adhering to these guidelines helps protect both your application and your candidates' information.

1. Secure API Key Storage: Never hardcode API keys directly into your application's source code. Instead, store them in environment variables, secret management services (e.g., AWS Secrets Manager, Google Secret Manager), or secure configuration files that are not committed to version control. This prevents accidental exposure and makes key rotation easier. The Google Cloud Secret Manager documentation provides general guidance on secure secret storage.
2. Use HTTPS for All API Communication: Always ensure that all communication with the Checkr API occurs over HTTPS. HTTPS encrypts data in transit, protecting API keys and sensitive payload data from interception and eavesdropping, which is a foundational aspect of secure web communication as outlined by the Mozilla Developer Network's explanation of HTTPS.
3. Implement Webhook Signature Verification: For all incoming webhooks from Checkr, rigorously verify the HMAC-SHA256 signature included in the X-Checkr-Signature header. This step confirms that the webhook payload originated from Checkr and has not been altered, protecting your system from spoofed or tampered notifications. Checkr provides specific instructions for verifying webhook signatures in their documentation.
4. Least Privilege Principle: Configure your API keys with the minimum necessary permissions required for your application's functionality. While Checkr's API keys typically grant broad access, understanding and auditing their scope is important. Regularly review the access levels associated with your API keys.
5. API Key Rotation: Establish a regular schedule for rotating your API keys. This practice limits the window of exposure if a key is compromised. When rotating, generate a new key, update your application, and then revoke the old key.
6. Error Handling and Logging: Implement robust error handling that avoids leaking sensitive information in logs or error messages. Log authentication failures for security monitoring, but ensure that API keys or other credentials are never logged.
7. Isolate Environments: Use separate API keys for your development, staging, and production environments. Checkr provides a sandbox environment with distinct test API keys, which should be used for all development and testing to prevent accidental operations on live data.
8. IP Whitelisting (if available/applicable): If Checkr offers IP whitelisting for API access, configure it to restrict API calls to only originate from your known server IP addresses. This adds an extra layer of security by blocking requests from unauthorized locations.