Use case: Refresh token

Trạng thái

Đã đóng sau valid login/session.

Service sở hữu

Identity Service.

API Gateway route public request tới Identity Service.

Endpoint

POST /api/auth/refresh

Yêu cầu xác thực

Không dùng Authorization.

Cần refreshToken từ body JSON field refreshToken hoặc HttpOnly cookie.

Mục tiêu

Verify refreshToken, rotate session, trả token set mới theo session stage.

Luồng request

Client
→ API Gateway
→ Identity Service
→ Database / token service
→ Response

Contract API

Request

Body có thể rỗng nếu cookie có token.

{
  "refreshToken": "refreshToken"
}

Success response

Branch session response:

{
  "success": true,
  "code": "AUTH_REFRESH_SUCCESS",
  "data": {
    "account": {},
    "workspace": {},
    "member": {},
    "branch": {},
    "auth": {
      "tokenType": "Bearer",
      "accessToken": "branch-scoped token",
      "accountAccessToken": "account-scoped token",
      "refreshToken": "refreshToken"
    },
    "nextAction": {
      "type": "load_current_context"
    }
  }
}

Account-stage response:

{
  "success": true,
  "code": "AUTH_REFRESH_SUCCESS",
  "data": {
    "branches": [],
    "auth": {
      "tokenType": "Bearer",
      "accountAccessToken": "account-scoped token",
      "refreshToken": "refreshToken"
    },
    "nextAction": {
      "type": "select_branch",
      "redirectTo": "/select-branch"
    }
  }
}

Error response

• VALIDATION_ERROR, MALFORMED_JSON.
• REFRESH_TOKEN_INVALID: token thiếu, sai, expired, revoked, hoặc jti không khớp.
• WORKSPACE_DISABLED, MEMBER_DISABLED, BRANCH_NOT_FOUND, BRANCH_DISABLED, BRANCH_ACCESS_DENIED.
• JWT_KEY_NOT_CONFIGURED.

Hành vi database

Read:

• identity.auth_session: load session bằng session_id.
• identity.account: check account active.
• identity.workspace_member, identity.branch_member, identity.branch, identity.role: rebuild session material.

Write:

• identity.auth_session: rotate jti, set status = 'ACTIVE', update expires_at.

Hành vi token/session

• Nếu body token và cookie token cùng tồn tại nhưng khác nhau, refresh invalid.
• Verify refreshToken và so khớp token jti với identity.auth_session.jti.
• Issue rotated refreshToken và set lại refresh HttpOnly cookie.
• Branch session trả branch-scoped accessToken.
• Account-stage session trả accountAccessToken + branches[].

Logs và observability

• Gateway log có route_id=identity-auth; Identity log có path=/api/auth/refresh.
• Không log refreshToken, cookie hoặc response token.

Tiêu chí nghiệm thu

• Happy path pass.
• Error path pass.
• Logs có request/correlation id nếu đi qua Gateway.
• Bruno/local smoke test pass nếu có.

TODO

Chưa đóng: browser-specific cookie behavior theo từng environment.