Leaked Credential Checks

Detect and prevent use of compromised credentials on your applications

The Leaked Credential Checks API helps protect your applications by detecting when users attempt to log in with credentials that have been exposed in data breaches. This service checks login attempts against a database of known leaked credentials.

Initialize the Leaked Credential Checks resource

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

const leakedCredentialChecks = client.leakedCredentialChecks;

Configuration

Enable Leaked Credential Checks

Enable or disable Leaked Credential Checks for a zone.

const config = await client.leakedCredentialChecks.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  enabled: true,
});

zone_id · string · required

Zone identifier

enabled · boolean

Enable or disable Leaked Credential Checks

Get configuration status

Retrieve the current status of Leaked Credential Checks.

const status = await client.leakedCredentialChecks.get({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

console.log(`Leaked Credential Checks enabled: ${status.enabled}`);

Detections

Manage custom detection patterns for identifying username and password fields in login requests.

Create detection

Create a user-defined detection pattern.

const detection = await client.leakedCredentialChecks.detections.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  username_expression: 'http.request.body.form["email"]',
  password_expression: 'http.request.body.form["password"]',
});

zone_id · string · required

Zone identifier

username_expression · string

Ruleset expression to match the username in a request. For example:

• http.request.body.form["email"]
• http.request.body.json["user"]
• http.request.headers["x-username"][0]

password_expression · string

Ruleset expression to match the password in a request. For example:

• http.request.body.form["password"]
• http.request.body.json["pass"]
• http.request.body.form["user_password"]

Update detection

Update an existing detection pattern.

const detection = await client.leakedCredentialChecks.detections.update(
  '18a14bafaa8eb1df04ce683ec18c765e',
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    username_expression: 'http.request.body.json["username"]',
    password_expression: 'http.request.body.json["password"]',
  }
);

List detections

List all user-defined detection patterns.

// Automatically fetches more pages as needed
for await (const detection of client.leakedCredentialChecks.detections.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(detection.id);
  console.log('Username:', detection.username_expression);
  console.log('Password:', detection.password_expression);
}

Get detection

Retrieve a specific detection pattern.

const detection = await client.leakedCredentialChecks.detections.get(
  '18a14bafaa8eb1df04ce683ec18c765e',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Delete detection

Remove a user-defined detection pattern.

const result = await client.leakedCredentialChecks.detections.delete(
  '18a14bafaa8eb1df04ce683ec18c765e',
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Use cases

Protect login forms

Set up detection for a standard HTML form login.

// Enable Leaked Credential Checks
await client.leakedCredentialChecks.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  enabled: true,
});

// Create detection pattern for form-based login
await client.leakedCredentialChecks.detections.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  username_expression: 'http.request.body.form["email"]',
  password_expression: 'http.request.body.form["password"]',
});

Protect JSON API logins

Set up detection for a JSON-based authentication API.

await client.leakedCredentialChecks.detections.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  username_expression: 'http.request.body.json["username"]',
  password_expression: 'http.request.body.json["password"]',
});

Multiple login endpoints

Create multiple detection patterns for different login endpoints.

// Main login endpoint
await client.leakedCredentialChecks.detections.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  username_expression: 'http.request.body.form["username"]',
  password_expression: 'http.request.body.form["password"]',
});

// API login endpoint
await client.leakedCredentialChecks.detections.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  username_expression: 'http.request.body.json["user"]',
  password_expression: 'http.request.body.json["pass"]',
});

// Admin login with different field names
await client.leakedCredentialChecks.detections.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  username_expression: 'http.request.body.form["admin_email"]',
  password_expression: 'http.request.body.form["admin_password"]',
});

Audit existing detections

Review all configured detection patterns.

console.log('Configured detection patterns:');

let count = 0;
for await (const detection of client.leakedCredentialChecks.detections.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  count++;
  console.log(`\nDetection ${count}:`);
  console.log(`  ID: ${detection.id}`);
  console.log(`  Username: ${detection.username_expression}`);
  console.log(`  Password: ${detection.password_expression}`);
}

console.log(`\nTotal detections: ${count}`);

Response types

LeakedCredentialCheckCreateResponse

Configuration status for Leaked Credential Checks.

enabled · boolean

Whether Leaked Credential Checks are enabled

LeakedCredentialCheckGetResponse

Current status of Leaked Credential Checks.

enabled · boolean

Whether Leaked Credential Checks are enabled

DetectionCreateResponse

User-defined detection pattern.

id · string

Unique ID for this custom detection

username_expression · string

Ruleset expression to match the username in a request

password_expression · string

Ruleset expression to match the password in a request

DetectionListResponse

List item for a detection pattern.

id · string

Unique ID for this custom detection

username_expression · string

Ruleset expression to match the username

password_expression · string

Ruleset expression to match the password

created_at · string

When the detection was created

updated_at · string

When the detection was last updated

Best practices

Test your expressions: Before deploying to production, test your username and password expressions to ensure they correctly identify the credential fields in your login requests.

Multiple endpoints: If your application has multiple login endpoints with different field names, create separate detection patterns for each.

Monitor alerts: Set up monitoring for leaked credential alerts to quickly identify and respond to potential account compromises.

Leaked Credential Checks can only detect credentials that match known data breaches. It should be used as part of a comprehensive security strategy that includes strong password policies, multi-factor authentication, and account monitoring.

Expression examples

Common expression patterns for different login implementations:

HTML form POST

// Standard form fields
username: http.request.body.form["username"]
password: http.request.body.form["password"]

// Email-based login
username: http.request.body.form["email"]
password: http.request.body.form["password"]

JSON API

// Standard JSON fields
username: http.request.body.json["username"]
password: http.request.body.json["password"]

// Nested JSON
username: http.request.body.json["credentials"]["user"]
password: http.request.body.json["credentials"]["pass"]

Headers

// Basic auth alternative
username: http.request.headers["x-username"][0]
password: http.request.headers["x-password"][0]

Related resources

• Bot Management
• Security Center
• Leaked Credentials Documentation