The Ocha API uses a two-role permission model. Every user is assigned either theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/floriansalvi/HEIG-VD_Ocha-api/llms.txt
Use this file to discover all available pages before exploring further.
user role or the admin role at registration time, and that role is stored on their document in the database. Access to each endpoint is enforced by one or two middleware layers — protect (authentication check) and admin (role check) — that run before the request reaches the controller.
Roles
| Role | Assigned by default | Description |
|---|---|---|
user | Yes | Standard authenticated access. Can place and manage own orders. |
admin | No | Full access including product, store, and order management. |
The role is set at registration and is stored directly on the user document. There is no self-service role upgrade; roles must be assigned at account creation or updated directly in the database by a database administrator.
How authentication is enforced
Requests to protected endpoints must include a valid JWT in theAuthorization header:
protect middleware verifies the token, decodes the user ID, fetches the user from the database (excluding the password), and attaches it to req.user. If the token is missing, invalid, or expired, the middleware returns 401 before the request reaches the controller.
The admin middleware runs after protect on admin-only endpoints. It checks that req.user.role === 'admin'. If the user is authenticated but not an admin, it returns 403.
Understanding 401 vs 403
| Status | Meaning |
|---|---|
401 Unauthorized | No token was provided, or the token is invalid or expired. The request is not authenticated. |
403 Forbidden | The token is valid and the user is authenticated, but the user does not have the admin role. |
Endpoint permissions
Public endpoints — no authentication required
These endpoints are accessible to any client without a token:| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/products | List all products |
GET | /api/v1/products/:id | Get a product by ID |
GET | /api/v1/stores | List all stores |
GET | /api/v1/stores/:id | Get a store by ID |
User endpoints — authentication required (user or admin)
These endpoints require a valid Bearer token. Both user and admin roles are accepted.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/orders | Create a new order |
GET | /api/v1/orders/:id | Get a specific order |
DELETE | /api/v1/orders/:id | Delete a specific order |
GET | /api/v1/orders/:id/items | Get items for a specific order |
GET | /api/v1/users | Get the authenticated user’s profile |
GET | /api/v1/users/orders | Get the authenticated user’s order history |
Admin endpoints — admin role required
These endpoints require a valid Bearer token and the admin role. A user-role token returns 403.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/products | Create a new product |
PATCH | /api/v1/products/:id | Update a product |
DELETE | /api/v1/products/:id | Delete a product |
PUT | /api/v1/products/:id/image | Upload or replace a product image |
POST | /api/v1/stores | Create a new store |
PATCH | /api/v1/stores/:id | Update a store |
DELETE | /api/v1/stores/:id | Delete a store |
PATCH | /api/v1/orders/:id | Update an order’s status |
GET | /api/v1/order-stats | Get aggregate order statistics |
Middleware implementation summary
Theprotect middleware (middleware/authMiddleware.js) handles 401 responses for:
- Missing
Authorizationheader or token - Token that fails
jwt.verify()(invalid signature, malformed, expired) - Token that decodes to a user ID not found in the database
admin middleware (middleware/adminMiddleware.js) handles 403 responses for:
- Authenticated users whose
rolefield is not'admin'
Next steps
Authentication
Learn how to register, log in, and obtain a JWT token.
Image upload
Upload product images using an admin token.
Error codes
Full list of error responses returned by the API.
Quickstart
Make your first authenticated API request in minutes.