Skip to content

API.md

Latest commit

 

History

History
112 lines (75 loc) · 2.53 KB

API.md

File metadata and controls

112 lines (75 loc) · 2.53 KB
Raw

Auth Service API Reference

Externally via gateway at /api/login, /api/signup, etc.
Full URL from browser: https://host/api/login → gateway strips /api → auth service gets /login.

Auth flow

  1. User submits credentials to POST /login or POST /signup
  2. Service responds with Set-Cookie: session_token=<token>; HttpOnly; Path=/; Max-Age=2592000
  3. Gateway automatically extracts this cookie and validates via POST /validate
  4. On success, gateway injects X-User-Id header to downstream services
  5. POST /logout clears the cookie

Headers

Header Required? Source Description
X-Session-Token for /logout, /validate Cookie extraction (gateway) Session token
X-User-Id for /account Gateway (from validation) User's snowflake ID

Error format

{ "error": "error_code", "message": "Human readable message" }
Status error_code Meaning
401 account_not_found Account does not exist
401 session_not_found Session expired or invalid
401 invalid_password Wrong password
404 user_not_found User not found
409 username_exists Username already taken
500 password_hash_failed Password processing error

Endpoints

POST /login — Log in (public)

Body:

{ "username": "alice", "password": "hunter2" }

Response 204 No Content.
Sets cookie: session_token=<hex>; HttpOnly; Path=/; Max-Age=2592000; SameSite=Lax
(Adds Secure flag in non-DEV environments)

Errors: account_not_found (401), invalid_password (401)

POST /signup — Create account (public)

Body: same as login.

Response 204 No Content.
Sets same cookie as login (auto-login after signup).

Errors: username_exists (409)

POST /logout — Log out (protected by SessionToken)

Header: X-Session-Token: <token>

Response 204 No Content.
Sets Set-Cookie: session_token=; Max-Age=0 (clears cookie).

POST /validate — Validate session token (internal, used by gateway)

Header: X-Session-Token: <token>

Response 200:

{ "user_id": "12345" }

user_id is null if token is expired or invalid.

GET /account — Get account info (protected by UserId)

Response 200:

{
  "username": "alice",
  "is_admin": false,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-06-11T12:00:00Z"
}

Password handling

  • Argon2id algorithm
  • Random salt per invocation
  • Hashed and verified server-side only