API Reference Overview
All IPFOS APIs are served through a single gateway. Locally that is http://localhost:8080; every path below is relative to it.
The reference pages in this section are generated from the platform's OpenAPI contract, synced from the production gateway (https://os.gateway.beagile.africa/openapi/openapi.yml) into openapi/api-spec.yml. The contract itself is authored in os-backend/docs/design/api-spec.yml and deployed with the gateway — so these pages always describe the API that is actually live.
Authentication
Obtain a JWT via the auth endpoints (Google sign-in or admin login), then send it on every request:
Authorization: Bearer <access token>
Tokens carry the user's role and resource:action permissions; each service enforces them. Refresh tokens rotate — use POST /api/v1/auth/refresh before the access token expires.
Conventions
- Response envelope: responses arrive wrapped as
{ data, message, path, status, timestamp }. - Pagination: list endpoints take
currentPage/pageSizeand return aPaginatedResponse. - IDs: all cross-service identifiers (
userId,departmentId,projectId) are UUIDs.
Route map
| Path prefix | Service |
|---|---|
/api/v1/auth, /api/v1/users, /api/v1/departments, /api/v1/projects, /api/v1/badges | os-auth-service |
/api/v1/tickets | os-tickets-service |
/api/v1/notifications | os-integration-service |
/api/v1/meals | os-meals-service |
Regenerating this reference
After a backend deploy (or whenever you want to refresh):
cd docs
pnpm update-api # fetch prod spec + regenerate all endpoint pages
Under the hood that runs two steps you can also use separately: pnpm sync-api-spec (downloads the prod spec into openapi/api-spec.yml; if production is unreachable it keeps the committed copy and the build is unaffected) and pnpm gen-api (regenerates the pages). The git diff of openapi/api-spec.yml after a sync is a readable record of what changed in the API.
The same spec also powers the Scalar viewer at https://os.gateway.beagile.africa/docs (and http://localhost:8080/docs when running the backend locally).