Use case: Login

Trạng thái

Đã đóng trong checkpoint Go Gateway + Go Identity.

Service sở hữu

Identity Service.

API Gateway chỉ route public request tới Identity Service.

Endpoint

POST /api/auth/login

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

Public. Không cần Authorization.

Mục tiêu

Validate account + credential, tạo auth_session, issue token set cho bước tiếp theo.

Luồng request

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

Contract API

Request

{
  "email": "user@example.test",
  "password": "string"
}

Success response

Single branch response:

{
  "success": true,
  "code": "AUTH_LOGIN_SUCCESS",
  "data": {
    "account": {},
    "workspace": {},
    "member": {},
    "branches": [],
    "auth": {
      "tokenType": "Bearer",
      "accessToken": "branch-scoped token",
      "refreshToken": "refreshToken",
      "expiresIn": 900,
      "refreshExpiresIn": 604800
    },
    "nextAction": {
      "type": "load_current_context"
    }
  }
}

Multi branch response:

{
  "success": true,
  "code": "AUTH_LOGIN_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.
• INVALID_CREDENTIALS: email/password sai hoặc credential không hợp lệ.
• ACCOUNT_LOCKED, ACCOUNT_DISABLED.
• WORKSPACE_DISABLED, MEMBER_DISABLED, BRANCH_CONTEXT_REQUIRED.
• JWT_KEY_NOT_CONFIGURED.

Hành vi database

Read:

• identity.account: lookup bằng email, check status.
• identity.credential: lookup credential_type = 'PASSWORD', check status.
• identity.workspace_member, identity.branch_member, identity.branch: lấy active member/branch.
• identity.member_role, identity.branch_member_role, identity.role: lấy role codes.

Write:

• identity.account: update last_login_at.
• identity.auth_session: create session ACTIVE, jti, expires_at.

Hành vi token/session

• Single branch: issue branch-scoped accessToken và refreshToken.
• Multi branch: issue accountAccessToken, refreshToken, trả branches[].
• refreshToken được set lại bằng HttpOnly cookie.
• System account có system token path riêng, không phải flow customer chính.

Logs và observability

• Gateway log có route_id=identity-auth; Identity log có request_id, correlation_id, path.
• Không log password, token, cookie, request body.

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: system admin login use case riêng.