BreachScan.ai

APIDocumentation

Everything you need to integrate BreachScan into your application signup/login flow: from quick usage to production-ready implementations.

Getting Started

BreachScan provides privacy-first checks using SHA256 hashes. Your users' credentials never leave your system - only partial hash prefixes are sent to our API.

How Anonymity-Preservation Works

Hash the credential using SHA-256 on your client
Send only the first 5 hexadecimal characters of the hash to our API
Receive all matching hash suffixes for that prefix
Check locally if any suffix completes your full hash
A complete match indicates the credential was exposed in known breaches

Privacy benefit: We never see your users' credentials, and all breach confirmation occurs locally.

Authentication

All API requests require an API key passed in the X-API-Key header.

X-API-Key: your-api-key-here

Base URL

https://api.breachscan.ai

Rate Limits

See your plan limits in the pricing section

Password Endpoint

GET/check-password/{prefix}Check password hash prefix

Where {prefix} is the first 5 hex characters of the SHA256 hash

Email Endpoint

GET/check-email/{prefix}Check email hash prefix

Where {prefix} is the first 5 hex characters of the SHA256 hash

Combo Endpoint

GET/check-combo/{email_prefix}/{password_prefix}Check email+password combination

Where {email_prefix} and {password_prefix} are the first 5 hex characters of each SHA256 hash

Password Breach Detection

Basic Implementation

Simple Node.js integration - just 8 lines of code! Perfect for server-side applications or quick prototyping.

javascript

// Simple password breach check
const checkPassword = async (password) => {
  // 1. Hash the password and get prefix
  const hash = crypto.createHash('sha256').update(password).digest('hex');
  const prefix = hash.substring(0, 5);
  
  // 2. Query API
  const response = await fetch(`https://api.breachscan.ai/check-password/${prefix}`, {
    headers: { 'X-API-Key': 'your-api-key' }
  });
  
  // 3. Check if password is breached
  const result = await response.json();
  const suffix = hash.substring(5);
  return result.suffixes.includes(suffix);
};

Production-Ready Implementation

Browser-compatible with timeout protection and graceful error handling. Recommended for production applications.

javascript

// Browser-compatible password check with timeout and error handling
const checkPassword = async (password, timeout = 3000) => {
  try {
    // Create timeout promise
    const timeoutPromise = new Promise((_, reject) => 
      setTimeout(() => reject(new Error('Timeout')), timeout)
    );
    
    // Create API call promise  
    const apiPromise = (async () => {
      // 1. Hash password using browser crypto API
      const encoder = new TextEncoder();
      const data = encoder.encode(password);
      const hashBuffer = await crypto.subtle.digest('SHA-256', data);
      const hashArray = Array.from(new Uint8Array(hashBuffer));
      const hash = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
      
      // 2. Query API with prefix
      const prefix = hash.substring(0, 5);
      const response = await fetch(`https://api.breachscan.ai/check-password/${prefix}`, {
        headers: { 'X-API-Key': 'your-api-key' }
      });
      
      if (!response.ok) throw new Error(`API error: ${response.status}`);
      
      // 3. Check if breached
      const result = await response.json();
      const suffix = hash.substring(5);
      return result.suffixes.includes(suffix);
    })();
    
    // Race API call against timeout
    return await Promise.race([apiPromise, timeoutPromise]);
    
  } catch (error) {
    console.warn('Breach check failed:', error.message);
    return false; // Never block login flow
  }
};

// Usage in login flow - never blocks authentication
const handleLogin = async (email, password) => {
  // Check breach status (non-blocking)
  const isBreached = await checkPassword(password);
  
  // Continue normal authentication
  const result = await authenticateUser(email, password);
  
  // Add warning if needed
  if (result.success && isBreached) {
    result.warning = 'Consider changing your password - it may be compromised.';
  }
  
  return result;
};

API Response Format

{
  "suffixes": [
    "a1b2c3d4e5f6789012345678901234567890abcd",
    "f6e5d4c3b2a1098765432109876543210fedcba",
    "1234567890abcdef1234567890abcdef12345678"
  ],
  "count": 3
}

Email Breach Detection

Basic Implementation

Check if an email address has been exposed in data breaches. Perfect for user registration flows to warn about compromised accounts.

javascript

// Simple email breach check
const checkEmail = async (email) => {
  // 1. Hash the email and get prefix
  const hash = crypto.createHash('sha256').update(email.toLowerCase()).digest('hex');
  const prefix = hash.substring(0, 5);
  
  // 2. Query API
  const response = await fetch(`https://api.breachscan.ai/check-email/${prefix}`, {
    headers: { 'X-API-Key': 'your-api-key' }
  });
  
  // 3. Check if email is breached
  const result = await response.json();
  const suffix = hash.substring(5);
  return result.suffixes.includes(suffix);
};

API Response Format

{
  "suffixes": [
    "a1b2c3d4e5f6789012345678901234567890abcd",
    "f6e5d4c3b2a1098765432109876543210fedcba",
    "1234567890abcdef1234567890abcdef12345678"
  ],
  "count": 3
}

Important Note

Email addresses are automatically normalized to lowercase before hashing. This ensures consistent results regardless of how users input their email.

Combination Breach Detection

Basic Implementation

Check if a specific email and password combination has been exposed together in the same breach. This is more targeted than checking credentials individually.

javascript

// Check email + password combination breach
const checkCombo = async (email, password) => {
  // 1. Hash both credentials and get prefixes
  const emailHash = crypto.createHash('sha256').update(email.toLowerCase()).digest('hex');
  const passwordHash = crypto.createHash('sha256').update(password).digest('hex');
  const emailPrefix = emailHash.substring(0, 5);
  const passwordPrefix = passwordHash.substring(0, 5);
  
  // 2. Query API with both prefixes
  const response = await fetch(`https://api.breachscan.ai/check-combo/${emailPrefix}/${passwordPrefix}`, {
    headers: { 'X-API-Key': 'your-api-key' }
  });
  
  // 3. Check if combination is breached
  const result = await response.json();
  const emailSuffix = emailHash.substring(5);
  const passwordSuffix = passwordHash.substring(5);
  
  return result.pairs.some(pair => 
    pair.email_suffix === emailSuffix && pair.password_suffix === passwordSuffix
  );
};

API Response Format

{
  "pairs": [
    {
      "email_suffix": "a85dcb0a57780fe6766e7b625656ce9e0a32b32334975e0485af48a6461",
      "password_suffix": "567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    },
    {
      "email_suffix": "b865e4566471b4ab2ea013082f2af56716c7e71f34eeb2c1f94c3b4361e8",
      "password_suffix": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba098765"
    }
  ],
  "count": 2
}

Use Cases

•High-security login flows requiring exact combination verification
•Account takeover prevention for sensitive applications
•Compliance requirements for credential compromise detection

APIDocumentation

Contents

Getting Started

How Anonymity-Preservation Works

Authentication

Base URL

Rate Limits

Password Endpoint

Email Endpoint

Combo Endpoint

Password Breach Detection

Basic Implementation

Production-Ready Implementation

API Response Format

Email Breach Detection

Basic Implementation

API Response Format

Important Note

Combination Breach Detection

Basic Implementation

API Response Format

Use Cases

Error Handling & Best Practices

Best Practices

Common HTTP Errors

Production Deployment Checklist