Flow
Auth và chọn branch
Flow FE-BE từ login tới khi có branch-scoped accessToken.
Auth và chọn branch
Mục tiêu
Đưa FE từ trạng thái chưa đăng nhập tới trạng thái có branch-scoped accessToken.
Chỉ cover Flow 1 login và Flow 2 select branch. Không cover current-context, setup, database hoặc business APIs.
Trạng thái
| Item | Trạng thái |
|---|---|
POST /api/auth/login | Đã đóng |
POST /api/auth/refresh | Đã đóng sau valid session |
POST /api/auth/select-branch | Đã đóng |
GET /api/workspaces/current-context | Route reachable, Entitlement chưa đóng |
GET /api/auth/me và POST /api/auth/logout tồn tại trong Go code nhưng chưa là checkpoint chính của flow này.
Service tham gia
FE
→ API Gateway
→ Identity ServiceAPI Gateway route auth requests tới Identity Service qua route_id=identity-auth.
Token dùng trong flow
| Token | Dùng khi nào | Không dùng cho |
|---|---|---|
accountAccessToken | select/switch branch | business/protected APIs |
accessToken | sau khi có branch context | select branch |
refreshToken | refresh session/token | gọi business API trực tiếp |
refreshToken có thể nằm trong body JSON field refreshToken hoặc HttpOnly cookie tùy client/runtime.
Flow 1 — Login
API sequence
FE
→ POST /api/auth/login
→ API Gateway
→ Identity Service
→ responseCase A — Single branch
- Input:
email,password. - Expected response:
auth.accessToken,auth.refreshToken,account,workspace,member,branches[],nextAction.type = load_current_context. - FE action: lưu
accessTokenlàm active token, lưu account/workspace/member/branches tối thiểu, đi Flow 3GET /api/workspaces/current-context.
Case B — Multi branch
- Input:
email,password. - Expected response:
auth.accountAccessToken,auth.refreshToken,account,workspace,member,branches[],nextAction.type = select_branch. - FE action: lưu
accountAccessTokentạm, render branch selection UI từbranches[], không gọi business/protected APIs.
Login error FE cần xử lý
| Error code | FE action |
|---|---|
VALIDATION_ERROR | Hiển thị lỗi field email/password. |
INVALID_CREDENTIALS | Hiển thị login failed, không giữ token cũ. |
ACCOUNT_LOCKED | Chặn login, hiển thị hướng liên hệ support. |
ACCOUNT_DISABLED | Chặn login, clear auth state. |
WORKSPACE_DISABLED / MEMBER_DISABLED | Chặn tiếp tục vào workspace. |
Flow 2 — Select branch
Khi nào gọi
Gọi khi login trả auth.accountAccessToken, branches[], nextAction.type = select_branch.
Request dùng branchId từ branches[].
API sequence
FE
→ POST /api/auth/select-branch
→ API Gateway
→ Identity Service
→ response branch-scoped accessTokenFE action sau khi success
- Lưu
auth.accessTokenlàm active token. - Bỏ hoặc hạ quyền
accountAccessTokenkhỏi business request path. - Lưu
workspace,member,branchđã chọn. - Clear branch selection UI state.
- Đi tiếp Flow 3:
GET /api/workspaces/current-context.
Select branch error FE cần xử lý
| Error code | FE action |
|---|---|
VALIDATION_ERROR | branchId thiếu/null; giữ màn chọn branch. |
TOKEN_MISSING | Clear auth state, quay lại login. |
TOKEN_INVALID | Clear auth state hoặc thử refresh nếu policy FE cho phép. |
TOKEN_EXPIRED | Thử refresh; nếu fail thì logout/clear auth state. |
BRANCH_NOT_FOUND / BRANCH_DISABLED | Reload branch list bằng login/refresh flow. |
BRANCH_ACCESS_DENIED | Clear selected branch, không retry cùng branchId. |
Refresh trong flow này
- First stale/missing
/api/auth/refreshtrả401là acceptable nếu sau đó login/refresh hợp lệ thành công. - Sau valid login/session, refresh should work.
- Refresh có thể update
accessToken,accountAccessToken,refreshToken,branches[]tùy session stage. - Nếu refresh fail bằng
REFRESH_TOKEN_INVALID, logout/clear auth state.
FE state tối thiểu
| State | Khi nào có |
|---|---|
account | Sau login/refresh success |
accountAccessToken | Multi branch stage hoặc refresh account-stage |
accessToken | Single branch login hoặc select branch success |
refresh/session cookie | Sau login/refresh nếu runtime dùng cookie |
branches | Login/refresh response khi cần branch selection |
selectedBranch | Sau select branch success |
authStage | Ví dụ: anonymous, select_branch, branch_ready |
Redirect rule
| Tình huống | FE action |
|---|---|
| Single branch login success | Đi Flow 3 current-context. |
| Multi branch login success | Mở branch selection UI. |
| Select branch success | Replace active token rồi đi Flow 3. |
| Invalid credentials | Ở lại login, clear token state. |
| Refresh failed | Logout/clear auth state, quay lại login. |
Không làm trong flow này
- Không gọi business API bằng
accountAccessToken. - Không tự build workspace context ở FE.
- Không xử lý setup/
current-contextở Flow 1/2. - Không dùng
GET /api/auth/me/branchesvì Go router chưa có endpoint này. - Không verify
JWTtrong FE để quyết định backend authorization.
Flow tiếp theo
Sau khi có branch-scoped accessToken, FE gọi:
GET /api/workspaces/current-contextAPI Gateway route này tới Entitlement Service. Route reachable through Gateway, nhưng Entitlement chưa đóng.