Authentication API

Portal authentication endpoints for user registration, login, 2FA, and session management.

POST /api/auth/register

Create a new portal user account.

Request:

{
  "email": "jane@example.com",
  "password": "securePassword123!"
}

Response (201):

{
  "ok": true,
  "user": {
    "id": "9a45a46a-adbf-4b27-b47a-9a01be67e947",
    "email": "jane@example.com",
    "emailVerified": false
  }
}

Sets portal_token httpOnly cookie.

POST /api/auth/login

Authenticate and create a session.

Request:

{
  "email": "jane@example.com",
  "password": "securePassword123!"
}

Response (200) — standard login:

{
  "ok": true,
  "user": {
    "id": "9a45a46a-adbf-4b27-b47a-9a01be67e947",
    "email": "jane@example.com",
    "orgId": "b2c3d4e5-f6a7-8901-bcde-f01234567890"
  }
}

Response (200) — 2FA required:

{
  "ok": true,
  "requires2FA": true,
  "tempToken": "eyJhbGciOiJIUzI1NiIs..."
}

Rate limit: 5 attempts per 15 minutes per IP.

POST /api/auth/logout

Destroy the current session.

Auth: Required (portal session cookie)

Response: 200, clears session cookie.

POST /api/auth/verify-email

Verify email address with token from verification email.

POST /api/auth/forgot-password

Request a password reset email.

Response: Always 200 (does not reveal if email exists).

POST /api/auth/reset-password

Reset password using token from reset email.

Two-Factor Authentication (2FA)

POST /api/auth/2fa/setup

Generate TOTP secret and QR code for 2FA setup.

Auth: Required

Response: { secret, qrCodeUrl, backupCodes[] }

POST /api/auth/2fa/verify-login

Verify TOTP code during login.

POST /api/auth/2fa/verify-backup-code

Use a backup code when TOTP device is unavailable.

POST /api/auth/2fa/disable

Disable 2FA for the current user.

Auth: Required

POST /api/auth/2fa/regenerate-backup-codes

Generate new backup codes (invalidates old ones).

Auth: Required

Session Management

GET /api/auth/account/sessions

List active sessions for the current user.

Auth: Required

Response: Array of { id, ipAddress, userAgent, createdAt, expiresAt }

GET /api/auth/account/profile

Get current user profile.

Auth: Required

PUT /api/auth/account/profile

Update user profile.

Auth: Required

POST /api/auth/account/change-password

Change password for authenticated user.

Organization Management

GET /api/auth/org/members

List members of the current organization.

Auth: Required

POST /api/auth/org/invitations

Invite a user to the organization.

POST /api/auth/accept-invitation

Accept an organization invitation.