API design

Base URL and prefix

All API endpoints are prefixed with /api/v1. better-auth endpoints live outside this prefix at /api/auth.

https://<backend-url>/api/v1/employees
https://<backend-url>/api/v1/orders
https://<backend-url>/api/auth/sign-in

REST conventions

HTTP method	Purpose	Example
`GET`	Read one or many	`GET /api/v1/employees/:id`
`POST`	Create, and non-CRUD operations (approve, reject, bulk actions)	`POST /api/v1/orders/:id/approve`
`PATCH`	Partial update	`PATCH /api/v1/employees/:id`
`DELETE`	Delete	`DELETE /api/v1/stores/:id`

MUZE does not use PUT. Bulk operations use dedicated POST /<resource>/bulk-deactivate and POST /<resource>/bulk-permanent endpoints that accept { ids: string[] } in a single request.

Response patterns

Single objects are returned directly. Lists are returned as arrays or wrapped in a { data: [], total: number } envelope depending on the endpoint. Errors follow a consistent shape (see Validation for how errors are produced):

{
  "statusCode": 400,
  "message": "These details are already in use. Please review them and try again.",
  "error": "Conflict"
}

Validation errors return the messages as an array:

{
  "statusCode": 400,
  "message": ["name should not be empty", "email must be an email"],
  "error": "Bad Request"
}

Authentication

All endpoints except /api/auth/* require a valid session. The session lives in an HTTP-only cookie managed by better-auth and sent automatically by the browser. No Authorization: Bearer header and no JWT tokens are involved. See Authentication.

Authorization decorators

Controllers declare required access with NestJS decorators:

@Permissions(Permission.EMPLOYEES_MANAGE)
@Post()
async create(@Body() dto: CreateEmployeeDto) { ... }

@RequireScope({ storeIdParam: 'storeId' })
@Get('stores/:storeId/employees')
async getStoreEmployees(@Param('storeId') storeId: string) { ... }

@Permissions(...) uses AND semantics; the legacy @Roles(...) decorator uses OR semantics. See Authorization for the full model.

File uploads

File uploads use multipart/form-data or JSON-wrapped CSV payloads and are validated at the service level. Import endpoints use dedicated routes such as POST /api/v1/employees/import.

Client scoping parameters

Client-scoped list endpoints accept an optional clientId query parameter. The rule is narrow, never widen: admins may filter to any client, HR can only narrow within their assigned client, and Store Manager requests ignore the parameter entirely. See Client isolation.

Rate limiting

All endpoints are rate-limited to 100 requests per 60-second window. There are no per-route overrides and rate-limit headers are not exposed to the client.

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Base URL and prefix

REST conventions

Response patterns

Authentication

Authorization decorators

File uploads

Client scoping parameters

Rate limiting

​Base URL and prefix

​REST conventions

​Response patterns

​Authentication

​Authorization decorators

​File uploads

​Client scoping parameters

​Rate limiting

Base URL and prefix

REST conventions

Response patterns

Authentication

Authorization decorators

File uploads

Client scoping parameters

Rate limiting