Password Exposure API
SpyCloud’s Password Exposure API lets you safely check whether a password has appeared in past exposures using k-anonymity, so you can enforce NIST-aligned policies without sending full passwords or full hashes.
🚨 The Challenge
Breaches, infostealer-infected devices, and credential phishing continuously leak passwords. NIST 800-63B recommends checking new and reset passwords against known-compromised lists—yet many organizations avoid it over privacy, compliance, or security concerns.
✅ What This API Helps You Do
- Block risky passwords: Detect if proposed passwords (or their hashes) were seen exposed before and reject per policy.
- Meet compliance: Enforce NIST 800-63B guidance using k-anonymity so no full password/hash leaves your environment.
- Scale securely: Integrate a simple REST check into signup, reset, and rotation flows with minimal latency.
Privacy by design: You only send a 5-character hash prefix. SpyCloud returns potential matches so you can evaluate locally—your full hash never leaves your system.
⚙️ How It Works
- Hash the password — Compute one of the supported hash types (SHA-1, SHA-256, SHA-512, or NTLM).
- Send the prefix — Submit the first 5 hex characters of the hash with a
typeparameter. - Evaluate locally — Compare returned candidate suffixes (and metadata) against your full hash to decide whether to allow/deny the password.
🧰 Request & Response
Requests
| Parameter | Purpose |
|---|---|
hash_prefix (5 hex) | First 5 characters of the password hash. |
type | One of: sha1, sha256, sha512, ntlm. |
Example
GET /nist-password-v2/check/hashes/edb9b?type=sha1
(Example: password _sprinkles_ → SHA-1 edb9b4a7ec13377a368ba4e88bb9e121c99ed425)
Responses Returned as RESTful JSON with candidate matches for that prefix.
| Field (selected) | What you get |
|---|---|
hash_suffix | Remaining hex suffix of the hash (to join with prefix). |
exposure_count | Count of times this hash appeared in SpyCloud data. |
last_seen | Approximate most recent observation timestamp (UTC ISO-8601). |
sources | High-level exposure sources (e.g., breach/malware/phish). |
You compare
hash_prefix + hash_suffixagainst your locally computed full hash. If it matches and policy dictates, reject or step-up.
🧪 Common Uses
Account creation
Reject known-compromised passwords at signup.
Password reset
Prevent reuse of exposed passwords during recovery flows.
Periodic rotation
Enforce policies aligned to NIST 800-63B without handling cleartext.
🗃️ Data Sources
SpyCloud aggregates password exposures from malware-infected devices, phishing sites, and breaches, standardizing them for privacy-preserving checks via k-anonymity.
📈 Outcomes You Can Target
- Reduce account takeover (ATO) by eliminating known-weak passwords at the gate.
- Improve compliance posture while maintaining user privacy.
- Lower support & fraud costs by catching risky choices pre-incident.
🔍 Selected API Field Reference
| Field | Example | Description |
|---|---|---|
hash_prefix | edb9b | First 5 hex chars of the password hash you submit. |
type | sha1 | Hash algorithm used (sha1, sha256, sha512, ntlm). |
hash_suffix | 4a7ec13377a368ba4e88bb9e121c99ed425 | Suffix you compare locally with your full hash. |
exposure_count | 17 | Number of times this hash was observed. |
last_seen | 2023-01-01T00:00:00Z | Most recent observation timestamp (UTC). |
sources | ["breach","malware"] | High-level exposure sources for context. |
📎 Integration Notes
- Delivery: RESTful API with JSON output.
- Privacy: Only a 5-char prefix is transmitted; full matching occurs on your side.
- Hashing: Supports SHA-1, SHA-256, SHA-512, NTLM.
- Docs: See API Guidelines for auth, config, and error handling; and the API Reference for exact schemas and examples.
Updated 15 days ago