4.3 KiB
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, device token, 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, push token registration, 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:
export FIREBASE_WEB_API_KEY="$(gcloud secrets versions access latest --secret=firebase-web-api-key --project=krow-workforce-dev)"
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
- attendance proof logs are durable in SQL and raw object storage
- device push tokens are durable in SQL and can be registered separately for client and staff apps
- 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 alerts are written to
notification_outbox, dispatched by the private Cloud Run worker servicekrow-notification-worker-v2, and recorded innotification_deliveries
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.