Login with username and password

POST https://app.speybooks.com/api/v1/auth/login

Authenticate with username (or email) and password. If TOTP is enabled, returns a temporary token valid for 5 minutes that must be exchanged via the TOTP verify endpoint. If TOTP is not enabled, returns full access and refresh tokens immediately.

The response includes a user object with the authenticated user's profile for immediate UI hydration.

Failed attempts are tracked. After 5 failures, the account is locked for 15 minutes. Successful login resets the counter.

Body parameters

password string required

Account password.

username string required

Username or email address.

Response

200 Login successful. Returns access and refresh tokens, or a temporary token if TOTP verification is required.

Show response fields

accessToken string

expiresIn integer

refreshToken string

user object

Show child attributes

email string

fullName string

id integer

isAdmin boolean

username string

Error codes

400 Validation error in login data.

401 Invalid credentials. Includes attemptsRemaining count.

423 Account locked due to too many failed attempts. Includes time remaining.

429 Rate limit exceeded.

Request POST /v1/auth/login curl

curl -X POST https://api.speybooks.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "..."}'

Response 200

{
  "success": true,
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "expiresIn": 900,
    "user": {
      "id": 1,
      "username": "user@example.com",
      "email": "user@example.com",
      "fullName": "Jane Doe",
      "isAdmin": false
    }
  }
}