Admin Login

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

string

required

The admin’s email address. Must be a valid email; matched case-insensitively.

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.

boolean

true on success.

object

Show data

object

The admin user record, including its bookkeeperOrg (id, name, slug, email, phone, timezone, dateFormat, overtimeThreshold, overtimeMultiplier, active). The passwordHash field is removed.

string

The JWT to send as Authorization: Bearer <token> on subsequent admin requests. Also set as the auth-token httpOnly cookie.

Errors

Status	`error`	Cause
`400`	`Invalid login data`	Body failed validation (e.g. malformed email).
`401`	`Authentication failed`	Email not found or password incorrect.
`403`	`Account inactive`	The admin user is deactivated.
`403`	`Organization inactive`	The admin’s bookkeeper organization is inactive.
`429`	`Too many login attempts`	Login rate limit exceeded.
`500`	`Login failed`	Unexpected 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!"
  }'

{
  "email": "sarah@acmebookkeeping.com",
  "password": "Admin123!"
}

{
  "success": true,
  "data": {
    "user": {
      "id": "0b6f...",
      "email": "sarah@acmebookkeeping.com",
      "firstName": "Sarah",
      "lastName": "Lee",
      "role": "SUPER_ADMIN",
      "active": true,
      "bookkeeperOrgId": "a1c2...",
      "lastLoginAt": "2026-06-17T14:03:11.000Z",
      "bookkeeperOrg": {
        "id": "a1c2...",
        "name": "Acme Bookkeeping",
        "slug": "acme-bookkeeping",
        "email": "billing@acmebookkeeping.com",
        "phone": "+15125550101",
        "timezone": "America/New_York",
        "dateFormat": "MM/DD/YYYY",
        "overtimeThreshold": 40,
        "overtimeMultiplier": 1.5,
        "active": true
      }
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Overview

Admin API

Employee API

Request body

Response

Errors

Examples

​Request body

​Response

​Errors

​Examples

Request body

Response

Errors

Examples