Skip to main content

Log in

POST 
/auth/login

Required role: none. This operation needs no credential.

Example request
curl --request POST \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/auth/login"

Username is matched case-insensitively, using simple lowercasing rather than full Unicode case folding. Password, plus a TOTP code once the account has TOTP enrolled. Rate-limited and lockout-protected per account and per source address: an unknown username and a wrong password against a real one get the same status and error code (invalid_credentials), reach lockout (rate_limited) at the same failure threshold, and cost the same bounded argon2id-shaped work either way, for similar timing, under ordinary load — under a sustained flood large enough to fill and evict from the unknown-username table's own 10,000-entry cap, an unknown username's lockout can lift early, where a real account's own (never capped or evicted) would not. Once the password is correct, totp_required (no code supplied) versus totp_invalid (a wrong one) does reveal that an account has TOTP enrolled — an unavoidable, rate-limited signal, not one this API tries to hide. The response also carries the session's second secret in the X-Hoserva-Session-Secret header (see the sessionCookie security scheme). A client sends it as a header and never stores it in a cookie.

Request​

Responses​

Signed in.

Response Headers
    Set-Cookie
    X-Hoserva-Session-Secret

    The session's second secret. A client keeps it in memory or session storage, never in a cookie, and sends it back as the X-Hoserva-Session-Secret request header on every request that authenticates with the session cookie.