Documentation for Product Version:
The Passwords API allows you to lookup whether a given password exists in our database of compromised passwords. A compromised password is any password which has been found in a data breach, a data exposure, or common password cracking dictionaries used by cybercriminals.
The typical example where this API can be useful is on your website’s signup and password change forms. When users attempt to establish a new password, you can check it against the Passwords API to determine if it is safe to use. If not, you can steer them clear from using it and require them to pick a different password. A good example of this is the Enzoic (formerly PasswordPing) Password Strength Meter control.
https://api.enzoic.com/passwords
Allows you to check whether a given password is known to be compromised, without needing to pass the exact password hash in. Rather than passing exact hashes of the password to the API, it is only necessary to supply the first 10 hex characters of each hash. A list of candidate hashes will then be returned and can be compared locally with the exact hash to determine if there was a match. This is the recommended approach for new implementations using the Passwords API.
See Using Enzoic for general instructions on using the API.
Request parameters should be passed as a JSON object in the request body.
| Parameter | Type | Description |
|---|---|---|
| partialSHA1 | string | The first 10 hex characters of the SHA-1 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| partialMD5 | string | The first 10 hex characters of the MD-5 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| partialSHA256 | string | The first 10 hex characters of the SHA-256 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| Response | Description |
|---|---|
| 200 | One or more possible candidate matches were found. The response body contains the candidates. If any of the candidate hashes match the exact hash, this is a compromised password, i.e. a “hacked” password. |
| 404 | No candidate matches were found in the database of compromised passwords – indicates password is not known to be compromised. |
The response body contains an array of candidate hashes which match one or more of the hash prefixes provided. Each candidate entry contains a boolean indicating whether the password was exposed in a data exposure. If this is false, the password was found in a common password cracking dictionary, but has not been seen in a breach. If the password is a breach password, it also contains a value indicating the relative frequency the password is seen.
| Member | Type | Description |
|---|---|---|
| candidates | PasswordHashCandidate[] |
| Member | Type | Description |
|---|---|---|
| md5 | string | The MD5 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match. |
| sha1 | string | The SHA1 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match. |
| sha256 | string | The SHA256 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match. |
| revealedInExposure | boolean | Whether the password was exposed in a known data Exposure. If this value is false, the password was found in common password cracking dictionaries, but has not been directly exposed as a user password in a data breach or other Exposure. |
| relativeExposureFrequency | integer | This is a gauge of how frequently the password has been seen in data breaches. The value is simply the percent of data breaches indexed by Enzoic that have contained at least one instance of this password, i.e. if the value is 13, that means 13% of the exposures that Enzoic has indexed contained this password at least one time. This value can be used to gauge how dangerous this password is by how common it is. |
| exposureCount | integer | The total number of exposures this password has appeared in. While it’s a bad idea to ever use a password that has been publicly exposed even a single time, this number can be used to determine how common a password is and how often it has been exposed. |
curl --header "authorization: basic {your auth string}" \
--header "content-type: application/json" \
--data '{ "partialSHA1": "a94a8fe5cc", "partialMD5": "098f6bcd46", "partialSHA256": "9f86d08188" }' \
https://api.enzoic.com/passwords
{
"candidates": [
{
"md5": "098f6bcd4621d373cade4e832627b4f6",
"sha1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"revealedInExposure": true,
"relativeExposureFrequency": 2
}
]
}
https://api.enzoic.com/passwords
Allows you to check whether a given password is known to be compromised, without needing to pass the exact password hash in. Rather than passing exact hashes of the password to the API, it is only necessary to supply the first 10 hex characters of each hash. A list of candidate hashes will then be returned and can be compared locally with the exact hash to determine if there was a match. This is the recommended approach for new implementations using the Passwords API.
See Using Enzoic for general instructions on using the API.
| Parameter | Type | Description |
|---|---|---|
| partial_sha1 | string | The first 10 hex characters of the SHA-1 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| partial_md5 | string | The first 10 hex characters of the MD-5 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| partial_sha256 | string | The first 10 hex characters of the SHA-256 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| Response | Description |
|---|---|
| 200 | One or more possible candidate matches were found. The response body contains the candidates. If any of the candidate hashes match the exact hash, this is a compromised password, i.e. a “hacked” password. |
| 404 | No candidate matches were found in the database of compromised passwords – indicates password is not known to be compromised. |
The response body contains an array of candidate hashes which match one or more of the hash prefixes provided. Each candidate entry contains a boolean indicating whether the password was exposed in a data exposure. If this is false, the password was found in a common password cracking dictionary, but has not been seen in a breach. If the password is a breach password, it also contains a value indicating the relative frequency the password is seen.
| Member | Type | Description |
|---|---|---|
| candidates | PasswordHashCandidate[] |
| Member | Type | Description |
|---|---|---|
| md5 | string | The MD5 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match. |
| sha1 | string | The SHA1 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match. |
| sha256 | string | The SHA256 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match. |
| revealedInExposure | boolean | Whether the password was exposed in a known data Exposure. If this value is false, the password was found in common password cracking dictionaries, but has not been directly exposed as a user password in a data breach or other Exposure. |
| relativeExposureFrequency | integer | This is a gauge of how frequently the password has been seen in data breaches. The value is simply the percent of data breaches indexed by Enzoic that have contained at least one instance of this password, i.e. if the value is 13, that means 13% of the exposures that Enzoic has indexed contained this password at least one time. This value can be used to gauge how dangerous this password is by how common it is. |
| exposureCount | integer | The total number of exposures this password has appeared in. While it’s a bad idea to ever use a password that has been publicly exposed even a single time, this number can be used to determine how common a password is and how often it has been exposed. |
curl --header "authorization: basic {your auth string}" \
"https://api.enzoic.com/passwords?partial_sha1=a94a8fe5cc&partial_md5=098f6bcd46&partial_sha256=9f86d08188"
{
"candidates": [
{
"md5": "098f6bcd4621d373cade4e832627b4f6",
"sha1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"revealedInExposure": true,
"relativeExposureFrequency": 2
}
]
}
https://api.enzoic.com/passwords
We recommend new implementations use the partial hash approach outlined below. Returns whether a given password is in the Enzoic database of compromised passwords. To lookup the status of a password, it is necessary to pass several different hashed versions of it. This is necessary since often breach data only contains a hashed version of a password and the hash format often varies between breaches.
See Using Enzoic for general instructions on using the API.
| Parameter | Type | Description |
|---|---|---|
| sha1 | string | A SHA-1 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| md5 | string | An MD-5 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| sha256 | string | A SHA-256 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing. |
| Response | Description |
|---|---|
| 200 | The password was found in the database of known compromised passwords, i.e. a “hacked” password. |
| 404 | The password was not found in the database of compromised passwords – indicates password is not known to be compromised. |
The response body contain a boolean indicating whether the password was exposed in a data exposure or was found in a common password cracking dictionary. If the password is a breach password, it also contains a value indicating the relative frequency the password is seen.
| Member | Type | Description | |||
|---|---|---|---|---|---|
| revealedInExposure | boolean | Whether the password was exposed in a known data Exposure. If this value is false, the password was found in common password cracking dictionaries, but has not been directly exposed as a user password in a data breach or other Exposure. | |||
| relativeExposureFrequency | integer | This is a gauge of how frequently the password has been seen in data breaches. The value is simply the percent of data breaches indexed by Enzoic that have contained at least one instance of this password, i.e. if the value is 13, that means 13% of the exposures that Enzoic has indexed contained this password at least one time. This value can be used to gauge how dangerous this password is by how common it is. | exposureCount | integer | The total number of exposures this password has appeared in. While it’s a bad idea to ever use a password that has been publicly exposed even a single time, this number can be used to determine how common a password is and how often it has been exposed. |
curl --header "authorization: basic {your auth string}" \
"https://api.enzoic.com/passwords?sha1=a94a8fe5ccb19ba61c4c0873d391e987982fbbd3&md5=098f6bcd4621d373cade4e832627b4f6&sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"