slp-modular-cms/aidlc-docs/_shared/reverse-engineering/api-documentation.md

API Documentation

REST APIs

Authentication

POST /auth/login

• Method: POST
• Path: /auth/login
• Purpose: Authenticate a user and receive JWT tokens
• Authorization: Anonymous
• Request: { "email": string, "password": string }
• Response: { "accessToken": string, "expiresAt": datetime, "user": { "id": guid, "email": string, "name": string, "role": string, "isActive": bool } }
• Cookie set: refreshToken (httpOnly, Secure, SameSite=Strict, Path=/api/v1/auth)

POST /auth/refresh

• Method: POST
• Path: /auth/refresh
• Purpose: Refresh an access token using the httpOnly refresh token cookie
• Authorization: Anonymous
• Request: (empty body — refresh token read from cookie)
• Response: Same as /auth/login (new access token + new cookie)

POST /auth/revoke

• Method: POST
• Path: /auth/revoke
• Purpose: Revoke a refresh token (logout)
• Authorization: Bearer JWT required
• Request: "<refreshToken>" (string body)
• Response: 204 No Content

---

Setup

GET /setup/status

• Method: GET
• Path: /setup/status
• Purpose: Check if the system has been initialized (first owner created)
• Authorization: Anonymous
• Response: { "initialized": boolean }

POST /setup/owner

• Method: POST
• Path: /setup/owner
• Purpose: Create the initial Owner account (only usable when system is not yet initialized)
• Authorization: Anonymous
• Request: { "email": string, "password": string }
• Response: { "message": string }

---

Users

POST /users/invite

• Method: POST
• Path: /users/invite
• Purpose: Invite a new user by email with a specified role
• Authorization: Bearer JWT, Policy: AdminOnly
• Request: { "email": string, "role": string }
• Response: { "inviteLink": string }

POST /users/complete-setup

• Method: POST
• Path: /users/complete-setup
• Purpose: Complete account setup using an invitation token
• Authorization: Anonymous
• Request: { "token": string, "password": string }
• Response: { "message": string }

GET /users/validate-invitation

• Method: GET
• Path: /users/validate-invitation?token={token}
• Purpose: Validate an invitation token before showing the setup form
• Authorization: Anonymous
• Response: { "valid": boolean, "email": string, "role": string } or error

---

Availability

GET /availability/status

• Method: GET
• Path: /availability/status
• Purpose: Get current system availability status
• Authorization: Anonymous
• Response: { "status": "Available|Maintenance|Unavailable", "checkedAt": datetime, "message": string }

POST /availability/admin/status

• Method: POST
• Path: /availability/admin/status
• Purpose: Update the system availability status
• Authorization: Bearer JWT, Policy: OwnerOnly
• Request: { "newStatus": "Available|Maintenance|Unavailable", "reason": string }
• Response: 200 OK or 400 Bad Request

---

Authorization Policies

Policy	Required Role	Description
OwnerOnly	Owner	Full system access including availability management
AdminOnly	Owner or Admin	User management access

Data Models

AuthResponse

• accessToken — short-lived JWT (e.g. 15 min)
• refreshToken — long-lived opaque token
• expiresAt — access token expiry datetime
• user — authenticated user info

Password Validation Rules (enforced by backend)

Configured in ServiceCollectionExtensions.cs via ASP.NET Core Identity PasswordOptions:

• RequiredLength = 8 — minimum 8 characters
• RequireUppercase = true — at least 1 uppercase letter
• RequireLowercase = true — at least 1 lowercase letter
• RequireDigit = true — at least 1 digit
• RequireNonAlphanumeric = true — at least 1 non-alphanumeric character (e.g. !@#$%^&*)

ApplicationUser (returned in auth responses)

• id — Guid
• email — string
• name — string (display name)
• role — string (Owner / Admin / User)
• isActive — boolean

Invitation

• token — string (URL-safe token)
• email — string
• role — string
• expiryDate — datetime
• isUsed — boolean