Skip to content
Passwordify
Documentation

API reference

Everything you need to add real strength scoring, breach screening and NIST-aligned policy validation to your signup and reset flows. Every endpoint is a POST request that exchanges JSON — no SDK required. Machine-readable spec: OpenAPI 3 (openapi.json).

Overview

What the API does

Passwordify's REST API brings the same checks that power the free browser tools to your backend: real strength scoring from zxcvbn, breach screening against the Have I Been Pwned corpus (900M+ passwords) via k-anonymity, policy validation aligned with NIST 800-63B, and password or passphrase generation from a cryptographically secure random source (CSPRNG). Drop it into a signup form, a password reset flow, or an internal admin tool.

Base URL

https://www.passwordify.xyz/api

Format

Every endpoint is a POST. Send and receive application/json.

Auth

Authentication

Every request needs an API key, sent in the X-API-Key header:

X-API-Key: pk_live_...

Don't have a key yet? Every example on this page also works with the free, rate-limited demo key pk_test_passwordify_demo — no signup required. Create a production key on the Developers page when you're ready to go live.

Example

quickstart.sh
# Try it immediately with the free demo key (rate-limited) curl https://www.passwordify.xyz/api/v1/strength \ -H "X-API-Key: pk_test_passwordify_demo" \ -H "Content-Type: application/json" \ -d '{"password":"Summer2024!"}' # -> 200 OK { "score": 2, "guesses": 10010000, "entropyBits": 23.254938638385443, "crackTimeOfflineFast": { "seconds": 0.001001, "display": "less than a second" }, "crackTimeOnline": { "seconds": 360360000, "display": "11 years" }, "feedback": { "warning": null, "suggestions": [ "Add more words that are less common.", "Capitalize more than the first letter." ] } }

Keys are secrets. Call Passwordify from your backend only. Never ship a pk_live_ key inside client-side JavaScript, a mobile app binary, or a public repository — the demo key above is the only one safe to expose.

Limits

Rate limits

Each plan has a monthly request quota, plus an hourly burst limit that protects the service from runaway loops (Free 600 / Pro 6,000 requests per hour; the public demo key is capped at 60 per hour). Need more headroom? See pricing.

Tier Requests / month Notes
Free 1,000 1 key, community support
Pro 100,000 1 key, email support

Every response includes your current hourly burst usage:

  • X-RateLimit-Limit requests allowed per hour for your plan
  • X-RateLimit-Remaining requests left in the current hourly window
  • X-RateLimit-Reset seconds until the hourly window resets

Keys with a monthly quota also receive X-Quota-Limit, X-Quota-Used, X-Quota-Remaining and X-Quota-Period (the calendar month, e.g. 202611).

Example — exceeding your quota

429-response.http
# Exceeding the hourly burst limit HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1800 { "error": { "code": "rate_limited", "message": "Burst rate limit exceeded. Please slow down and try again shortly." } } # Exceeding your plan's monthly quota HTTP/1.1 429 Too Many Requests X-Quota-Limit: 1000 X-Quota-Used: 1001 X-Quota-Remaining: 0 { "error": { "code": "quota_exceeded", "message": "Monthly quota of 1,000 requests exceeded for the Free plan. Upgrade for more headroom." } }
Errors

Errors

Failed requests return a non-2xx HTTP status and a JSON body with the same shape:

error.json
{ "error": { "code": "missing_field", "message": "\"password\" is required and must be a non-empty string." } }
Status Code Meaning
400 missing_field, invalid_field, invalid_json Missing or malformed request body or field
401 unauthorized Missing, invalid, or revoked API key
429 rate_limited, quota_exceeded Hourly burst limit or monthly quota exceeded
502 upstream_error The upstream breach-check service could not be reached — safe to retry with backoff
Reference

Endpoints

Four endpoints cover strength, breach, policy validation, and generation. Every one is a POST with a JSON body and a JSON response.

POST /v1/strength

Score a password's real-world strength with zxcvbn's pattern, dictionary, and keyboard-walk matching — far more accurate than a length-and-character-class regex meter.

Parameters

Parameter Type Required Description
password string Yes Plaintext password to score. Never logged or persisted.
userInputs string[] No Context words (username, email, site name) that count against the score if reused in the password.

Example

strength.sh
# Score a password as the user types curl https://www.passwordify.xyz/api/v1/strength \ -H "X-API-Key: pk_live_..." \ -H "Content-Type: application/json" \ -d '{"password":"Summer2024!","userInputs":["emanuele","passwordify"]}' # -> 200 OK { "score": 2, "guesses": 10010000, "entropyBits": 23.254938638385443, "crackTimeOfflineFast": { "seconds": 0.001001, "display": "less than a second" }, "crackTimeOnline": { "seconds": 360360000, "display": "11 years" }, "feedback": { "warning": null, "suggestions": [ "Add more words that are less common.", "Capitalize more than the first letter." ] } }
POST /v1/breach

Check whether a password appears in the Have I Been Pwned corpus using k-anonymity towards Have I Been Pwned — only a 5-character SHA-1 prefix is forwarded upstream. Note that this API itself receives either the plaintext password or the full SHA-1 hash, so the lookup is not k-anonymous towards Passwordify.

Parameters

Parameter Type Required Description
password string One of password, or sha1Prefix + sha1Suffix Plaintext password to check. Hashed on our side; only a 5-character prefix is forwarded to Have I Been Pwned.
sha1Prefix string With sha1Suffix First 5 hex characters of the SHA-1 hash, for callers that hash client-side. Send together with sha1Suffix. This is forwarded to Have I Been Pwned.
sha1Suffix string With sha1Prefix The remaining 35 hex characters of the SHA-1 hash. It is sent to this API (so we receive the full hash) but is not forwarded upstream; it is matched here against the range returned for the prefix.

Example

breach.sh
# Check a plaintext password (hashed on our side; only a 5-char prefix is forwarded to HIBP) curl https://www.passwordify.xyz/api/v1/breach \ -H "X-API-Key: pk_live_..." \ -H "Content-Type: application/json" \ -d '{"password":"password"}' # -> 200 OK (the count changes as the corpus grows) { "breached": true, "count": 52372427 } # Or hash client-side and send the SHA-1 split into prefix (5) + suffix (35). # The API receives the full hash in this mode; only the prefix is forwarded to HIBP: # SHA-1("password") = 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8 curl https://www.passwordify.xyz/api/v1/breach \ -H "X-API-Key: pk_live_..." \ -H "Content-Type: application/json" \ -d '{"sha1Prefix":"5BAA6","sha1Suffix":"1E4C9B93F3F0682250B6CF8331B7EE68FD8"}'
POST /v1/validate

Combine strength scoring and breach screening against a configurable NIST 800-63B policy in one call — the endpoint most signup and reset flows use directly.

Parameters

Parameter Type Required Description
password string Yes Plaintext password to validate.
policy object No Overrides for minLength (default 8), recommendedLength (default 15), maxLength (default 64), and screenBreaches (default true).

Example

validate.sh
# Screen a password at signup — strength + breach + policy curl https://www.passwordify.xyz/api/v1/validate \ -H "X-API-Key: pk_live_..." \ -H "Content-Type: application/json" \ -d '{"password":"Summer2024!","policy":{"minLength":12}}' # -> 200 OK (breachCount changes as the corpus grows) { "valid": false, "score": 2, "breached": true, "breachCount": 3614, "violations": ["too_short", "found_in_breach"], "feedback": { "warning": null, "suggestions": [ "Add more words that are less common.", "Capitalize more than the first letter." ] }, "policy": { "minLength": 12, "recommendedLength": 15, "maxLength": 64, "screenBreaches": true } }
POST /v1/generate

Generate cryptographically strong passwords or diceware-style passphrases from a CSPRNG — nothing pseudo-random, nothing seeded from a timestamp.

Parameters

Parameter Type Required Description
mode "password" | "passphrase" No Generation mode. Default "password".
length number No Character count in password mode (8–128). Default 20.
count number No Number of results to return. Default 1, max 100.
lowercase boolean No Include lowercase letters. Default true.
uppercase boolean No Include uppercase letters. Default true.
numbers boolean No Include digits. Default true.
symbols boolean No Include symbols. Default true.
avoidAmbiguous boolean No Exclude visually ambiguous characters (l, 1, I, O, 0). Default false.
words number No Word count in passphrase mode (3–12). Default 5.
separator string No Separator between words in passphrase mode. Default "-".
capitalize boolean No Capitalize each word in passphrase mode. Default true.
includeNumber boolean No Append one random digit to one word in passphrase mode. Default true.

Example

generate.sh
# A memorable diceware passphrase, two variants curl https://www.passwordify.xyz/api/v1/generate \ -H "X-API-Key: pk_live_..." \ -H "Content-Type: application/json" \ -d '{"mode":"passphrase","words":5,"separator":"-","count":2}' # -> 200 OK (output is random — yours will differ) { "passwords": [ "Payphone-Immodest1-Unleaded-Cornea-Slackness", "Daydream-Unjustly5-Wrinkly-Vineyard-Uplifted" ], "entropyBits": 67.94599061291628 }
Guides

Code examples

The same /v1/validate call, in four languages.

validate.sh
curl https://www.passwordify.xyz/api/v1/validate \ -H "X-API-Key: pk_live_..." \ -H "Content-Type: application/json" \ -d '{"password":"Summer2024!"}'