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,
});
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"]',
});
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]
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
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.
Whether Leaked Credential Checks are enabled
LeakedCredentialCheckGetResponse
Current status of Leaked Credential Checks.
Whether Leaked Credential Checks are enabled
DetectionCreateResponse
User-defined detection pattern.
Unique ID for this custom detection
Ruleset expression to match the username in a request
Ruleset expression to match the password in a request
DetectionListResponse
List item for a detection pattern.
Unique ID for this custom detection
Ruleset expression to match the username
Ruleset expression to match the password
When the detection was created
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"]
// Basic auth alternative
username: http.request.headers["x-username"][0]
password: http.request.headers["x-password"][0]