Password Hash Lifecycle¶
Three endpoints cover the full lifecycle of a stored password credential:
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/auth/hash-password |
Hash a plaintext password (bcrypt / argon2id / scrypt) |
POST |
/v1/auth/verify-password |
Verify a password against a stored hash, auto-detecting the algorithm |
POST |
/v1/auth/password-strength |
Score a password 0–4 with crack-time and entropy |
The interesting part is verify-password's needs_rehash flag: it tells you when a valid login used a hash that's weaker than your current policy, which is exactly when you should re-hash the plaintext you already have in hand and update the row. That's online rehashing without ever asking the user to reset.
Individual endpoint pages: Hash Password, Verify Password, Password Strength.
Base URL¶
https://auth.toolkitapi.io
All endpoints require an X-API-Key header.
1. Hash a password¶
Request¶
| Field | Type | Default | Constraints |
|---|---|---|---|
password |
string | — | Required |
algorithm |
string | bcrypt |
bcrypt, argon2, or scrypt |
rounds |
integer | null | algorithm default | ≥ 1. Meaning depends on the algorithm: bcrypt cost (default 12, must be 4–31), argon2 time_cost (default 3), scrypt log2(N) (default 14) |
Response¶
| Field | Type | Description |
|---|---|---|
hash |
string | Encoded hash, including algorithm identifier and parameters |
algorithm |
string | Echo of the requested algorithm |
parameters |
object | Effective parameters — see table below |
parameters differs per algorithm:
algorithm |
parameters |
|---|---|
bcrypt |
{"cost": 12} |
argon2 |
{"time_cost": 3, "memory_cost": 65536, "parallelism": 4, "type": "argon2id"} |
scrypt |
{"n": 16384, "r": 8, "p": 1, "salt_length": 16, "dk_length": 32} |
Argon2 uses argon2id specifically — not argon2i or argon2d. Scrypt hashes use the custom encoded form $scrypt$ln=14,r=8,p=1$<salt_hex>$<hash_hex>, which verify-password parses back.
curl -X POST "https://auth.toolkitapi.io/v1/auth/hash-password" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"password": "MyS3cur3P@ssword!", "algorithm": "argon2"}'
{
"hash": "$argon2id$v=19$m=65536,t=3,p=4$c2FsdHNhbHQ$aGFzaGhhc2hoYXNo",
"algorithm": "argon2",
"parameters": {
"time_cost": 3,
"memory_cost": 65536,
"parallelism": 4,
"type": "argon2id"
}
}
import requests
def hash_password(pw: str, algorithm: str = "argon2") -> str:
r = requests.post(
"https://auth.toolkitapi.io/v1/auth/hash-password",
headers={"X-API-Key": API_KEY},
json={"password": pw, "algorithm": algorithm},
timeout=30,
)
r.raise_for_status()
return r.json()["hash"]
const r = await fetch("https://auth.toolkitapi.io/v1/auth/hash-password", {
method: "POST",
headers: {
"X-API-Key": process.env.TOOLKIT_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ password: pw, algorithm: "bcrypt", rounds: 12 }),
});
const { hash, parameters } = await r.json();
Choosing an algorithm. Argon2id is the current recommendation (memory-hard, side-channel resistant). bcrypt is fine and ubiquitous. scrypt is fine but the least commonly supported by third-party verifiers. Whatever you pick, store the returned hash string verbatim — it's self-describing, so verification needs no separate metadata.
2. Verify a password¶
Request¶
| Field | Type | Description |
|---|---|---|
password |
string | Plaintext password from the login form |
hash |
string | Stored hash string |
Response¶
| Field | Type | Description |
|---|---|---|
valid |
boolean | Whether the password matches |
algorithm_detected |
string | bcrypt, argon2, or scrypt |
needs_rehash |
boolean | Hash is valid but below current recommended parameters |
needs_rehash rules, per algorithm:
| Algorithm | true when |
|---|---|
bcrypt |
Cost extracted from the hash is < 12 |
argon2 |
The argon2 library reports the hash's parameters are outdated (check_needs_rehash) |
scrypt |
ln (log2 N) is < 14 |
Detection is by prefix: $2b$ / $2a$ / $2y$ → bcrypt, $argon2… → argon2, $scrypt$ → scrypt. Any other format is a 400, not a valid: false — that distinction matters: a 400 means your stored data is corrupt, a 200 with valid: false means wrong password.
curl -X POST "https://auth.toolkitapi.io/v1/auth/verify-password" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"password": "MyS3cur3P@ssword!",
"hash": "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"
}'
{ "valid": true, "algorithm_detected": "bcrypt", "needs_rehash": false }
3. The login-with-upgrade pattern¶
This is the whole reason verify-password exists. Verify, and if the hash is stale, re-hash the plaintext you already have:
ROUTER = "https://auth.toolkitapi.io"
ALGO = "argon2" # current policy
def login(email: str, password: str) -> bool:
row = db.fetch_one("SELECT id, password_hash FROM users WHERE email = %s", (email,))
if row is None:
# Still burn time on a dummy hash to equalise timing.
verify(password, "$2b$12$" + "x" * 53)
return False
result = requests.post(
f"{ROUTER}/v1/auth/verify-password",
headers={"X-API-Key": API_KEY},
json={"password": password, "hash": row["password_hash"]},
timeout=30,
).json()
if not result["valid"]:
return False
if result["needs_rehash"]:
fresh = requests.post(
f"{ROUTER}/v1/auth/hash-password",
headers={"X-API-Key": API_KEY},
json={"password": password, "algorithm": ALGO},
timeout=30,
).json()["hash"]
db.execute(
"UPDATE users SET password_hash = %s, hash_updated_at = now() WHERE id = %s",
(fresh, row["id"]),
)
logger.info("rehashed credentials for user %s", row["id"])
return True
async function login(email, password) {
const row = await db.userByEmail(email);
if (!row) return false;
const v = await postJSON("/v1/auth/verify-password", {
password,
hash: row.password_hash,
});
if (!v.valid) return false;
if (v.needs_rehash) {
const { hash } = await postJSON("/v1/auth/hash-password", {
password,
algorithm: "argon2",
});
await db.updateHash(row.id, hash);
}
return true;
}
Because the upgrade happens on a successful login, there is no migration job and no user-visible change: users keep their old passwords and their stored hashes silently get stronger the next time they sign in.
Operational notes¶
- Never log
passwordorhashfrom these requests. Salted hashes are still sensitive; a leaked DB dump plus a leaked request log is worse than either alone. - Rate-limit verify calls. They're deliberately expensive by design (that's the point of bcrypt/argon2). Put a per-account and per-IP limiter in front of login, and consider a lockout after repeated
valid: false. - Tune
roundsto your latency budget, not to a number you saw in a blog post. Hash a password, measure p95, aim for ~100–250 ms. Bcrypt cost 12 and argon2idtime_cost=3, memory_cost=65536are sensible starting points. - Changing policy later is easy — flip
ALGOin the code above and every active user is upgraded on their next login. Users who never log in keep their old hashes, which is fine: those credentials are unusable anyway if the format is ever retired. hash-passwordaccepts any string. It does no strength checking. Runpassword-strengthat signup (see Password Strength) and rejectscore < 2before hashing.- Deterministic hashing is elsewhere. For non-password use cases (checksums, cache keys) use Hash; for message authentication use HMAC.
Errors¶
| Status | Condition |
|---|---|
400 |
Unknown algorithm; bcrypt rounds outside 4–31; unparseable hash on verify; scrypt parameters malformed |
401 |
Missing / invalid API key |
422 |
Missing password / hash field, or algorithm outside the allowed pattern |
500 |
Hashing failed inside the library (rare — retry, then investigate) |
See also¶
- Passwords — overview of the password endpoints
- Hash Password — endpoint reference
- Verify Password — endpoint reference
- Password Strength — strength scoring at signup
- Generate Password — generating compliant credentials