Authentication API Endpoints

This page provides the complete API reference for the Authentication service.

OpenAPI Specification

The complete OpenAPI specification for the Authentication API is available at openapi.yaml.

Authentication Flows

Staff Login Flow

// 1. Login with credentials
const loginResponse = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'admin@grandplaza.com',
    password: 'secure-password',
    organizationSlug: 'grand-plaza-hotel'
  })
});

const { accessToken, refreshToken, user } = await loginResponse.json();

// 2. Use token for authenticated requests
const profileResponse = await fetch('/api/v1/auth/me', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Token Refresh Flow

// Refresh expired access token
const refreshResponse = await fetch('/api/v1/auth/refresh', {
  method: 'POST',
  headers: {
    'X-Refresh-Token': refreshToken
  }
});

const { accessToken: newAccessToken } = await refreshResponse.json();

Password Reset Flow

// 1. Request password reset
await fetch('/api/v1/auth/forgot-password', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    organizationSlug: 'grand-plaza-hotel'
  })
});

// 2. Reset password with token from email
await fetch('/api/v1/auth/reset-password', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'reset_token_from_email',
    newPassword: 'newSecurePassword123'
  })
});

Error Handling

The API uses standard HTTP status codes and returns consistent error responses:

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

Common error codes:

• 400 - Bad Request (validation errors)
• 401 - Unauthorized (authentication failed)
• 403 - Forbidden (insufficient permissions)
• 423 - Locked (account locked due to failed attempts)
• 429 - Too Many Requests (rate limiting)
• 500 - Internal Server Error