Passwords API


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 PasswordPing Password Strength Meter control.

Available Calls

  • GET Password (legacy)
    Check whether a given password is in the PasswordPing database of compromised passwords.
  • GET Password By Partial Hash
    Check whether a given password is in the PasswordPing database of compromised passwords using a more secure, partial hash approach.

GET Password


https://api.passwordping.com/passwords

We recommend new implementations use the partial hash approach outlined below. Returns whether a given password is in the PasswordPing 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 PasswordPing for general instructions on using the API.

Request

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

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.

Response Body

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 PasswordPing that have contained at least one instance of this password, i.e. if the value is 13, that means 13% of the exposures that PasswordPing 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.

Example

curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/passwords?sha1=a94a8fe5ccb19ba61c4c0873d391e987982fbbd3&md5=098f6bcd4621d373cade4e832627b4f6&sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"

GET Password by Partial Hash


https://api.passwordping.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 PasswordPing for general instructions on using the API.

Request

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

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.

Response Body

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[]

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 PasswordPing that have contained at least one instance of this password, i.e. if the value is 13, that means 13% of the exposures that PasswordPing 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.

Example

Request
curl --header "authorization: basic {your auth string}" "https://api.passwordping.com/passwords?partial_sha1=a94a8fe5cc&partial_md5=098f6bcd46&partial_sha256=9f86d08188"
Response
{
  "candidates": [
    {
      "md5": "098f6bcd4621d373cade4e832627b4f6",
      "sha1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "revealedInExposure": true,
      "relativeExposureFrequency": 2
    }
  ]
}