Skip to main content
Authenticate a bookkeeper admin user with email and password. On success returns the admin record plus a JWT, and sets an auth-token cookie. 
POST /api/v1/auth/login
Authentication: none (this is how you obtain a token). Rate limit: 5 attempts per 15 minutes, per client IP (returns 429 when exceeded).

​
Request body

​
email
string
required
The admin’s email address. Must be a valid email; matched case-insensitively.
​
password
string
required
The admin’s password. Must be at least 1 character (verified against the stored bcrypt hash).

​
Response

On success returns 200 with the authenticated admin user (password hash stripped) and a signed JWT.
​
success
boolean
true on success.
​
data
object

​
Errors

StatuserrorCause
400Invalid login dataBody failed validation (e.g. malformed email).
401Authentication failedEmail not found or password incorrect.
403Account inactiveThe admin user is deactivated.
403Organization inactiveThe admin’s bookkeeper organization is inactive.
429Too many login attemptsLogin rate limit exceeded.
500Login failedUnexpected server error.
Failed and successful logins are both audit-logged with the client IP and user agent. Account inactive and Organization inactive are returned before the password is checked once the user is found.

​
Examples

curl -X POST https://app.paypunch.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sarah@acmebookkeeping.com",
    "password": "Admin123!"
  }'