REST API Reference

Complete endpoint specification, request/response contracts, and error formats for the Flockbase API.

The Flockbase backend exposes a RESTful JSON API built with NestJS and documented with OpenAPI / Swagger.

Production API: https://api.flockbase.live
Interactive Swagger UI: https://api.flockbase.live/docs
Authentication: Authorization: Bearer <accessToken>

Standard Error Response Format

All API errors return a consistent JSON payload:

{
  "statusCode": 400,
  "code": "UNIT_INVITE_TOKEN_INVALID",
  "message": "The invite token has expired or is invalid.",
  "timestamp": "2026-09-12T10:00:00.000Z"
}

Authentication Endpoints

`POST /auth/login`

Authenticates a user using email and password credentials.

Body: { "email": string, "password": string }
Response (Trusted Device): { "requiresOtp": false, "accessToken": string, "refreshToken": string }
Response (Unrecognized Device): { "requiresOtp": true, "reference": string, "devOtpCode"?: string }

`POST /auth/verify-otp`

Completes 2FA by verifying the 6-digit Termii PIN.

Body: { "reference": string, "code": string, "trustDevice"?: boolean }
Response: { "accessToken": string, "refreshToken": string }

`POST /auth/refresh`

Rotates an expired access token using a valid refresh token.

Body: { "refreshToken": string }
Response: { "accessToken": string, "refreshToken": string }

`POST /auth/logout`

Revokes the current refresh token and clears session cookies.

User & Profile Endpoints

`GET /users/me`

Retrieves the profile and unit details for the authenticated user.

`PATCH /users/me`

Updates user display profile fields (name, phone).

`PATCH /users/me/password`

Updates the authenticated user's password and revokes all other active sessions.

Body: { "currentPassword": string, "newPassword": string }
Response: 204 No Content

Admin Account Endpoints (`SUPER_ADMIN` Only)

Method	Endpoint	Description
`GET`	`/admin/admin-accounts`	List all administrators and super administrators.
`POST`	`/admin/admin-accounts`	Provision an admin account and dispatch welcome email.
`PATCH`	`/admin/admin-accounts/:id/deactivate`	Deactivate an admin and terminate all active sessions.
`POST`	`/admin/admin-accounts/:id/promote`	Promote an admin to `SUPER_ADMIN` (enforces max 5 cap).

Unit & Invite Endpoints

Method	Endpoint	Access	Description
`GET`	`/units`	Worker+	List all units.
`POST`	`/units`	Admin+	Create a new church unit.
`GET`	`/units/:id`	Worker+	Get unit details and leader info.
`GET`	`/units/:id/invite`	Unit Leader+	Retrieve current invite token and link.
`POST`	`/units/:id/invite/regenerate`	Unit Leader+	Revoke current token and generate new link.
`POST`	`/units/:id/invites/send-email`	Unit Leader+	Send branded invitation email to a recipient.
`GET`	`/units/public/invite/:token`	Public	Resolve invite token to safe unit name.

Worker Management Endpoints

Method	Endpoint	Access	Description
`GET`	`/workers`	Unit Leader+	List workers (scoped to unit for leaders; global for admins).
`POST`	`/workers`	Unit Leader+	Register a worker directly into a unit.
`GET`	`/workers/:id`	Unit Leader+	Retrieve worker profile.
`PATCH`	`/workers/:id`	Unit Leader+	Update worker details.
`PATCH`	`/workers/:id/deactivate`	Unit Leader+	Soft-deactivate a worker.

Attendance & Excuses Endpoints

Method	Endpoint	Access	Description
`GET`	`/services`	Worker+	List past and upcoming church services.
`POST`	`/services`	Admin+	Schedule a new service.
`POST`	`/attendance/qr`	Worker+	Check in using dynamic QR token.
`POST`	`/attendance/self`	Worker+	Self check-in during active service window.
`POST`	`/attendance/manual`	Unit Leader+	Roll-call check-in with mandatory reason note.
`GET`	`/excuses`	Unit Leader+	List excuses awaiting review.
`POST`	`/excuses`	Worker+	Submit an absence excuse for a service.
`PATCH`	`/excuses/:id/review`	Unit Leader+	Approve or reject a submitted excuse.

Governance & Auditing Endpoints (`ADMIN` & `SUPER_ADMIN`)

Method	Endpoint	Description
`GET`	`/governance/audit-logs`	Query organization audit ledger.
`POST`	`/governance/blocked-accounts/:id/block`	Block account with mandatory reason string.
`DELETE`	`/governance/blocked-accounts/:id/block`	Unblock an account and restore active status.

On this page