Krow-workspace/docs/BACKEND/API_GUIDES/V2/unified-api.md

Unified API V2

This service exists so frontend can use one base URL without forcing backend into one codebase.

Base idea

Frontend talks to one service:

• krow-api-v2

That gateway does two things:

1. exposes auth/session endpoints
2. forwards requests to the right internal v2 service

Route groups

Auth

• POST /auth/client/sign-in
• POST /auth/client/sign-up
• POST /auth/sign-out
• POST /auth/client/sign-out
• POST /auth/staff/sign-out
• GET /auth/session

Proxy passthrough

• /core/* -> core-api-v2
• /commands/* -> command-api-v2
• /query/* -> query-api-v2

Mobile read models

These are served by query-api-v2 but frontend should still call them through the unified host:

• /query/client/*
• /query/staff/*

Why this shape

• frontend gets one base URL
• backend keeps separate read, write, and service helpers
• we can scale or refactor internals later without breaking frontend paths

Current auth note

Client email/password auth is wrapped here.

Staff phone OTP is not wrapped here yet. That still needs its own proper provider-backed implementation rather than a fake backend OTP flow.