Auth

Authentication and session management. SpeyBooks uses JWT-based authentication with optional TOTP two-factor.

Login flow

  1. POST /auth/login with username/password
  2. If TOTP enabled: returns tempToken → POST /auth/totp/verify
  3. Returns accessToken (15min) and refreshToken (7 days)
  4. Refresh via POST /auth/refresh before access token expires

Security features

  • Passwords hashed with Argon2id (65536 KiB, 3 iterations)
  • Account lockout after 5 failed attempts (15 minutes)
  • Token generation tracking — password changes invalidate all refresh tokens
  • TOTP uses RFC 6238 (Google Authenticator compatible)
  • Rate limiting on all public auth endpoints
  • Constant-time responses to prevent user enumeration

Endpoints

POST https://app.speybooks.com/api/v1/auth/login Login with username and password POST https://app.speybooks.com/api/v1/auth/logout Logout GET https://app.speybooks.com/api/v1/auth/me Get current user POST https://app.speybooks.com/api/v1/auth/password Change password POST https://app.speybooks.com/api/v1/auth/refresh Refresh access token DELETE https://app.speybooks.com/api/v1/auth/totp Disable TOTP POST https://app.speybooks.com/api/v1/auth/totp/enable Verify and enable TOTP POST https://app.speybooks.com/api/v1/auth/totp/setup Generate TOTP secret for setup POST https://app.speybooks.com/api/v1/auth/totp/verify Verify TOTP code POST https://app.speybooks.com/api/v1/email-verification/verify-email Verify email with token POST https://app.speybooks.com/api/v1/email-verification/verify-email/send Send verification email to current user GET https://app.speybooks.com/api/v1/email-verification/verify-email/status Check email verification status POST https://app.speybooks.com/api/v1/password-reset/forgot-password Request password reset email POST https://app.speybooks.com/api/v1/password-reset/reset-password Reset password with token GET https://app.speybooks.com/api/v1/password-reset/reset-password/validate Validate a password reset token POST https://app.speybooks.com/api/v1/registration/register Register a new user and organisation