126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# 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, "refreshToken": string, "expiresAt": datetime, "user": { "id": guid, "email": string, "naam": string, "role": string } }`
|
|
|
|
#### POST /auth/refresh
|
|
- **Method**: POST
|
|
- **Path**: `/auth/refresh`
|
|
- **Purpose**: Refresh an access token using a valid refresh token
|
|
- **Authorization**: Anonymous
|
|
- **Request**: `{ "accessToken": string, "refreshToken": string }`
|
|
- **Response**: Same as `/auth/login`
|
|
|
|
#### 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
|
|
|
|
### ApplicationUser (returned in auth responses)
|
|
- `id` — Guid
|
|
- `email` — string
|
|
- `naam` — string (display name)
|
|
- `role` — string (Owner / Admin / User)
|
|
- `isActive` — boolean
|
|
|
|
### Invitation
|
|
- `token` — string (URL-safe token)
|
|
- `email` — string
|
|
- `role` — string
|
|
- `expiryDate` — datetime
|
|
- `isUsed` — boolean
|