Customer Authentication API

The Customer Authentication API provides endpoints for customer registration, login, and account management. This is separate from the admin authentication and is designed for end-user self-service.

Register Customer

Create a new customer account.

POST /api/v1/customers/register
x-tenant-id: t_demo
Content-Type: application/json

Request Body

{
  "email": "customer@example.com",
  "password": "securepassword123",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+358401234567",
  "marketingOptIn": true,
  "smsOptIn": false,
  "termsAccepted": true,
  "privacyPolicyAccepted": true
}

Request Fields

Field	Type	Required	Description
email	string	Yes	Customer email address (unique per tenant)
password	string	Yes	Password (minimum 8 characters)
firstName	string	No	Customer's first name
lastName	string	No	Customer's last name
phone	string	No	Phone number (international format recommended)
marketingOptIn	boolean	No	Opt-in for marketing emails (default: false)
smsOptIn	boolean	No	Opt-in for SMS notifications (default: false)
termsAccepted	boolean	Yes	Must accept terms of service
privacyPolicyAccepted	boolean	Yes	Must accept privacy policy

Response

Status: 201 Created

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "customer": {
    "id": "cust_abc123",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+358401234567",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

Error Responses

400 Bad Request - Validation error

{
  "error": "VALIDATION_ERROR",
  "message": "Password must be at least 8 characters",
  "code": 400
}

409 Conflict - Email already registered

{
  "error": "EMAIL_EXISTS",
  "message": "An account with this email already exists",
  "code": 409
}

Login Customer

Authenticate an existing customer and obtain an access token.

POST /api/v1/customers/login
x-tenant-id: t_demo
Content-Type: application/json

Request Body

{
  "email": "customer@example.com",
  "password": "securepassword123"
}

Request Fields

Field	Type	Required	Description
email	string	Yes	Customer email address
password	string	Yes	Customer password

Response

Status: 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "customer": {
    "id": "cust_abc123",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+358401234567"
  }
}

Error Responses

401 Unauthorized - Invalid credentials

{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid email or password",
  "code": 401
}

Get Customer Profile

Retrieve the authenticated customer's profile.

GET /api/v1/customers/me
Authorization: Bearer <customer_token>
x-tenant-id: t_demo

Response

Status: 200 OK

{
  "id": "cust_abc123",
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+358401234567",
  "marketingOptIn": true,
  "smsOptIn": false,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z"
}

Update Customer Profile

Update the authenticated customer's profile information.

PATCH /api/v1/customers/me
Authorization: Bearer <customer_token>
x-tenant-id: t_demo
Content-Type: application/json

Request Body

{
  "firstName": "John",
  "lastName": "Smith",
  "phone": "+358409876543",
  "marketingOptIn": false
}

Response

Status: 200 OK

{
  "id": "cust_abc123",
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "phone": "+358409876543",
  "marketingOptIn": false,
  "smsOptIn": false,
  "updatedAt": "2025-01-15T12:00:00.000Z"
}

Get Customer Bookings

Retrieve all bookings for the authenticated customer.

GET /api/v1/customers/me/bookings
Authorization: Bearer <customer_token>
x-tenant-id: t_demo

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status (e.g., "confirmed", "hold")
from	string	No	Filter bookings from date (ISO 8601)
to	string	No	Filter bookings to date (ISO 8601)
page	number	No	Page number for pagination (default: 1)
limit	number	No	Items per page (default: 20, max: 100)

Response

Status: 200 OK

{
  "bookings": [
    {
      "id": "booking_abc123",
      "status": "confirmed",
      "productName": "Laser Tag Session",
      "startsAt": "2025-01-20T14:00:00.000Z",
      "endsAt": "2025-01-20T15:00:00.000Z",
      "partySize": 4,
      "grandTotal": 100.0,
      "currency": "EUR",
      "reference": "BK-2025-01-20-001"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

Account Creation During Checkout

Customers can create an account during the booking checkout flow. This provides a seamless experience where:

1. Customer enters contact details during checkout
2. Customer opts in to create an account by checking the checkbox
3. Customer provides a password
4. After successful payment, the account is automatically created
5. Customer receives a welcome email with login instructions

Checkout Flow Integration

When processing a booking with account creation:

// During checkout, customer info includes account creation flags
const customerInfo = {
  customerEmail: 'customer@example.com',
  customerName: 'John Doe',
  customerPhone: '+358401234567',
  createAccount: true, // Opt-in for account creation
  password: 'securepassword123', // Password for new account
  termsAccepted: true, // Required for account creation
};

// After payment success, account is created automatically
// Customer is logged in and token is stored

Benefits for Customers

• Single checkout: No need to register separately
• Immediate access: Account is ready after payment
• Booking linked: New bookings are automatically linked to account
• Future convenience: Faster checkout for repeat customers

Token Usage

Customer tokens work similarly to admin tokens but with customer-specific permissions:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-tenant-id: t_demo

Token Scope

Customer tokens provide access to:

• View and manage own bookings
• Update own profile
• View booking history
• Cancel or reschedule own bookings (subject to policies)

Customer tokens do NOT provide access to:

• Admin endpoints
• Other customers' data
• System configuration
• Reporting and analytics

Security Considerations

1. Password Requirements: Minimum 8 characters
2. Email Verification: Recommended to verify email before full access
3. Token Storage: Store tokens securely (HttpOnly cookies recommended)
4. HTTPS Only: Always use HTTPS in production
5. Rate Limiting: Login attempts are rate-limited to prevent brute force