User Authentication API

The User Authentication API provides endpoints for user registration, passwordless login via magic links, social OAuth (Google, Facebook), and two-factor authentication (2FA/TOTP).

Registration

Create Account

Register a new user with organization and brand setup.

POST /api/auth/register
Content-Type: application/json

Request Body

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "secure-password-123",
  "orgName": "My Company"
}

Response

{
  "success": true
}

Sets an httpOnly session cookie for automatic login. Creates:

• User account with Stripe customer
• Default organization
• Default brand with admin access

Error Responses

Magic Link Authentication

Passwordless login via email magic links.

Request Magic Link

POST /api/auth/magic-link
Content-Type: application/json

Request Body

{
  "email": "user@example.com"
}

Response

{
  "success": true,
  "message": "Check your email for the magic link."
}

Verify Magic Link

GET /api/auth/magic-link/verify?token=abc123...

Automatically redirects to /admin on success, or /login?error=... on failure.

Error Redirects

OAuth Authentication

Google OAuth

Initiate Google Login

GET /api/auth/google

Redirects to Google OAuth consent screen.

Google Callback

GET /api/auth/google/callback?code=...

Handles OAuth callback. Creates or links account, then redirects to /admin.

Facebook OAuth

Initiate Facebook Login

GET /api/auth/facebook

Redirects to Facebook OAuth consent screen.

Facebook Callback

GET /api/auth/facebook/callback?code=...

Handles OAuth callback. Creates or links account, then redirects to /admin.

OAuth Behavior

1. New User: Creates account with OAuth profile, default organization, and brand
2. Existing User (by email): Links OAuth account to existing user
3. Returning OAuth User: Logs in directly

Two-Factor Authentication (2FA)

TOTP-based two-factor authentication using authenticator apps.

Get 2FA Setup

Get setup information for enabling 2FA.

GET /api/auth/2fa/setup

Requires: Session cookie

Response (2FA Not Enabled)

{
  "enabled": false,
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/SendPayLinks:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=SendPayLinks"
}

Use otpauth_url to generate a QR code for authenticator apps.

Response (2FA Already Enabled)

{
  "enabled": true
}

Confirm 2FA Setup

Enable 2FA by confirming a valid TOTP code.

POST /api/auth/2fa/confirm
Content-Type: application/json

Requires: Session cookie

Request Body

{
  "secret": "JBSWY3DPEHPK3PXP",
  "token": "123456"
}

Response

{
  "success": true
}

Verify 2FA Code

Complete login with 2FA verification.

POST /api/auth/2fa/verify
Content-Type: application/json

Request Body

{
  "userId": "user_123",
  "token": "123456"
}

Response

{
  "success": true
}

Sets session cookie on successful verification.

Error Responses

OAuth Configuration

Environment Variables

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Facebook OAuth
FACEBOOK_APP_ID=your-facebook-app-id
FACEBOOK_APP_SECRET=your-facebook-app-secret

OAuth Redirect URIs

Configure these callback URLs in your OAuth provider settings:

Security Best Practices

1. Magic Links: Tokens expire after a single use
2. 2FA: Use TOTP with 30-second time windows
3. Sessions: httpOnly cookies prevent XSS attacks
4. OAuth: State parameter prevents CSRF attacks
5. Passwords: Hashed with bcrypt before storage