API Guide

See the OpenAPI specification for the detailed contract of each endpoint.

---

Endpoint Summary

All routes use the /api/v1 prefix. Authentication via Authorization: Bearer <JWT> + X-Device-Id header.

Health & Meta

Method	Route	Roles	Description
GET	/api/v1/health	Public	Service health check
GET	/.well-known/security.txt	Public	RFC 9116

Authentication

Method	Route	Roles	Description
POST	/api/v1/auth/login	Public	Login (email + password) — rate limit: 5/min
POST	/api/v1/auth/refresh	Public	Renew access token — rate limit: 10/min
POST	/api/v1/auth/revoke	Authenticated	Revoke current session
POST	/api/v1/session/validate	Authenticated	Validate active session

Students

Method	Route	Roles	Description
GET	/api/v1/students	Authenticated	List students (paginated, search)
POST	/api/v1/students	ADMIN, CADASTRO	Create student
PATCH	/api/v1/students/:studentId	ADMIN, CADASTRO	Update student
POST	/api/v1/students/:studentId/delete	ADMIN	Soft-delete student (justification required)

Attendance

Method	Route	Roles	Description
POST	/api/v1/attendance/events	CHAMADOR, ADMIN	Mark a student present

Classes

Method	Route	Roles	Description
GET	/api/v1/classes	Authenticated	List classes
POST	/api/v1/classes	ADMIN	Create class
PATCH	/api/v1/classes/:classId	ADMIN	Update class
POST	/api/v1/classes/:classId/delete	ADMIN	Soft-delete class

Nuclei

Method	Route	Roles	Description
GET	/api/v1/nuclei	Authenticated	List nuclei
POST	/api/v1/nuclei	ADMIN	Create nucleus
PATCH	/api/v1/nuclei/:nucleusId	ADMIN	Update nucleus
POST	/api/v1/nuclei/:nucleusId/delete	ADMIN	Soft-delete nucleus

Users

Method	Route	Roles	Description
GET	/api/v1/users	ADMIN	List users
POST	/api/v1/users	ADMIN	Create user
PATCH	/api/v1/users/:userId	ADMIN	Update user
POST	/api/v1/users/:userId/reset-password	ADMIN	Reset password
POST	/api/v1/users/:userId/deactivate	ADMIN	Deactivate user

Roles

Method	Route	Roles	Description
GET	/api/v1/roles	ADMIN	List roles
POST	/api/v1/roles	ADMIN	Create custom role
PATCH	/api/v1/roles/:roleName	ADMIN	Update role
DELETE	/api/v1/roles/:roleName	ADMIN	Delete role (non-system)

Sync

Method	Route	Roles	Description
POST	/api/v1/sync/events	CHAMADOR, ADMIN, CADASTRO	Batch wrapper — processes multiple events
POST	/api/v1/sync/event	Authenticated	Processes 1 event atomically via D1.batch()

Dev

Method	Route	Roles	Description
POST	/_seed	—	Demo data seed (development only)

---

Required Headers (Authenticated Requests)

Header	Value
Authorization	Bearer <accessToken>
X-Device-Id	UUID v4 identifying the device
Idempotency-Key	UUID v4 (all mutations: POST, PATCH)

Error Format

All errors follow the envelope:

{
  "error": "ERROR_CODE",
  "message": "Human-readable description",
  "details": {}
}

Status	Code	Meaning
400	VALIDATION_FAILED	Invalid body or missing required header
401	UNAUTHORIZED	Token missing, invalid, or expired
401	COMPROMISED_SESSION	Refresh token reused (possible theft)
403	FORBIDDEN_ROLE	Role not allowed for the endpoint
404	NOT_FOUND	Route not found
409	IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD	Idempotency key reused with a different payload
500	CONFIG_ERROR	Server configuration error

---

Source: router.ts + workers/CONTEXT.md