Skip to main content

Documentation 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.

Ocha API uses JSON Web Tokens (JWT) for authentication. When you register or log in, the API returns a signed token that is valid for 7 days. You include this token in the Authorization header of every request that requires authentication. There are no sessions or cookies — the token is the only credential the server recognises after login.

​
How tokens work

Tokens are signed with JWT_SECRET using the HS256 algorithm and embed the user’s id and role. The server verifies the token on every protected request without querying a session store. If the token is missing, invalid, or expired, the request is rejected with 401 Unauthorized.
Tokens expire exactly 7 days after they are issued. There is no refresh mechanism — you must log in again to obtain a new token.

​
Registering a user

Send a POST request to /api/v1/auth with a JSON body containing email, password, and display_name. The phone field is optional. 
curl -X POST http://localhost:5001/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Password_123!",
    "display_name": "your_username"
  }'
A successful registration returns HTTP 201: 
{
  "message": "User successfully registered",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "6641f2c3a4e2b10012d3e456",
    "email": "[email protected]",
    "display_name": "your_username"
  }
}

​
Field requirements

Password — must be at least 8 characters and include all of the following:
  • 1 uppercase letter
  • 1 lowercase letter
  • 1 number
  • 1 special character
display_name — must be 3–30 characters, using only letters, numbers, and underscores. Must be unique across all accounts.
Both email and display_name must be unique. Registration returns 409 Conflict if either is already in use.

​
Logging in

Send a POST request to /api/v1/auth/login with your email and password. 
curl -X POST http://localhost:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Password_123!"
  }'
A successful login returns HTTP 200: 
{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "6641f2c3a4e2b10012d3e456",
    "email": "[email protected]",
    "display_name": "your_username"
  }
}
The API intentionally returns the same error message (“Email or password incorrect”) for both an unknown email and a wrong password. This prevents account enumeration.

​
Using the token

Include the token in every request to a protected endpoint using the Authorization header with the Bearer scheme. 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Full example retrieving your user profile: 
curl http://localhost:5001/api/v1/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
User roles

All accounts are assigned the user role by default at registration. The admin role must be set directly in the database.
RoleAccess
userRead public resources, create orders, view own profile and order history
adminAll user actions plus create/update/delete products and stores, view order statistics

​
Understanding 401 vs 403

StatusMeaningCommon cause
401 UnauthorizedThe request could not be authenticatedToken is missing, expired, or invalid
403 ForbiddenThe request was authenticated but the role is insufficientA user tried to access an admin-only route
If you receive 401, obtain a fresh token by logging in. If you receive 403, the endpoint requires the admin role which cannot be self-assigned.

Build docs developers (and LLMs) love

Get started for freeTalk to us