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 password or hash from 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 rounds to 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 argon2id time_cost=3, memory_cost=65536 are sensible starting points.
  • Changing policy later is easy — flip ALGO in 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-password accepts any string. It does no strength checking. Run password-strength at signup (see Password Strength) and reject score < 2 before 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