V2 Backend API Guide
This is the frontend-facing source of truth for the v2 backend.
1) Use one base URL
Frontend should call one public gateway:
API_V2_BASE_URL=https://krow-api-v2-933560802882.us-central1.run.app
Frontend should not call the internal core, command, or query Cloud Run services directly.
2) Current status
The unified v2 gateway is ready for frontend integration in dev.
What was validated live against the deployed stack:
- client sign-in
- staff auth bootstrap
- client dashboard, billing, coverage, hubs, vendors, managers, team members, orders, and reports
- client coverage incident feed for geofence and override review
- client hub, order, coverage review, and late-worker cancellation flows
- client invoice approve and dispute
- staff dashboard, availability, payments, shifts, profile sections, documents, certificates, attire, bank accounts, benefits, and time card
- staff availability, profile, tax form, bank account, shift apply, shift accept, clock-in, clock-out, location stream upload, and swap request
- direct file upload helpers and verification job creation through the unified host
- client and staff sign-out
The live validation command is:
source ~/.nvm/nvm.sh
nvm use 23.5.0
node backend/unified-api/scripts/live-smoke-v2-unified.mjs
The demo tenant can be reset with:
source ~/.nvm/nvm.sh
nvm use 23.5.0
cd backend/command-api
npm run seed:v2-demo
3) Auth and headers
Protected routes require:
Authorization: Bearer <firebase-id-token>
Write routes also require:
Idempotency-Key: <unique-per-user-action>
For now:
- backend wraps sign-in and sign-out
- frontend can keep using Firebase token refresh on the client
- backend is the only thing frontend should call for session-oriented API flows
All routes return the same error envelope:
{
"code": "STRING_CODE",
"message": "Human readable message",
"details": {},
"requestId": "uuid"
}
4) Attendance policy and monitoring
V2 now supports an explicit attendance proof policy:
NFC_REQUIREDGEO_REQUIREDEITHER
The effective policy is resolved as:
- shift override if present
- hub default if present
- fallback to
EITHER
For geofence-heavy staff flows, frontend should read the policy from:
GET /staff/clock-in/shifts/todayGET /staff/shifts/:shiftIdGET /client/hubs
Important operational rules:
- outside-geofence clock-ins can be accepted only when override is enabled and a written reason is provided
- NFC mismatches are rejected and are not overrideable
- background location streams are stored as raw batch payloads in the private v2 bucket and summarized in SQL for query speed
- incident review lives on
GET /client/coverage/incidents - confirmed late-worker recovery is exposed on
POST /client/coverage/late-workers/:assignmentId/cancel - queued manager alerts are written to
notification_outbox; this is durable notification orchestration, not a full push delivery worker yet
5) Route model
Frontend sees one base URL and one route shape:
/auth/*/client/*/staff/*- direct upload aliases like
/upload-fileand/staff/profile/*
Internally, the gateway still forwards to:
| Frontend use case | Internal service |
|---|---|
| auth/session wrapper | krow-api-v2 |
| uploads, signed URLs, model calls, verification workflows | core-api-v2 |
| writes and workflow actions | command-api-v2 |
| reads and mobile read models | query-api-v2 |
6) Frontend integration rule
Use the unified routes first.
Do not build new frontend work on:
/query/tenants/*/commands/*/core/*
Those routes still exist for backend/internal compatibility, but mobile/frontend migration should target the unified surface documented in Unified API.