Login Flow

Overview

This is the published SYSTEM sign-in sequence that establishes the JWT session used by all later portal calls. It is a short pre-login workflow built around initiate, optional MFA delivery, and complete.

Prerequisites

1. X-PORTAL-ACCESS-CODE: <system-portal-code>
2. a stable X-Client-Hash
3. a secure-channel session for encrypted request bodies
4. the user's email and password
5. storage for accessToken and refreshToken

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
X-Client-Hash: <browser-fingerprint>
X-Secure-Channel-Session-Id: <secure-channel-session-id>
Content-Type: application/json

Step-by-Step Flow

1. Initiate login

API endpoint: POST /web/v1/system/auth/login/initiate This validates the credentials and returns the short-lived login sessionId.

curl -X POST 'https://api.example.com/web/v1/system/auth/login/initiate' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'X-Client-Hash: <browser-fingerprint>' \
  -H 'X-Secure-Channel-Session-Id: <secure-channel-session-id>' \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"Str0ngP@ss!"}'

{"code":"2000","message":"SUCCESS","data":{"sessionId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","mfaMethods":[{"code":"EMAIL","value":10011001},{"code":"OTP","value":10011002}],"expiresIn":300}}

2. Send an MFA code when the chosen factor requires delivery

API endpoint: POST /web/v1/system/auth/login/mfa/send Call this for delivered factors such as email.

curl -X POST 'https://api.example.com/web/v1/system/auth/login/mfa/send' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'X-Client-Hash: <browser-fingerprint>' \
  -H 'X-Secure-Channel-Session-Id: <secure-channel-session-id>' \
  -H 'Content-Type: application/json' \
  -d '{"sessionId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","method":10011001}'

{"code":"2000","message":"SUCCESS","data":{"sent":true,"cooldownSeconds":60,"codeExpiresIn":300}}

3. Complete login with the MFA proof

API endpoint: POST /web/v1/system/auth/login/complete This verifies the selected MFA method and returns the JWT pair.

curl -X POST 'https://api.example.com/web/v1/system/auth/login/complete' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'X-Client-Hash: <browser-fingerprint>' \
  -H 'X-Secure-Channel-Session-Id: <secure-channel-session-id>' \
  -H 'Content-Type: application/json' \
  -d '{"sessionId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","method":10011001,"code":"123456"}'

{"code":"2000","message":"SUCCESS","data":{"accessToken":"eyJhbGciOi...example","refreshToken":"dGVzdC1yZWZyZXNoLXRva2VuLWV4YW1wbGU","expiresIn":3600}}

4. Confirm the authenticated session

API endpoint: GET /web/v1/system/profile The JWT is minimal, so fetch the live profile instead of decoding claims.

curl 'https://api.example.com/web/v1/system/profile' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"bizId":"ACC_SYS_001","accountEmail":"admin@example.com","accountName":"System Admin","accountPortal":{"code":"SYSTEM","value":10010101,"label":"System"}}}

Decision Points

1. if mfaMethods contains EMAIL, call the send endpoint before prompting for the code
2. if mfaMethods contains OTP, the user may enter the authenticator code directly
3. if the response indicates pending approval, stop routing into the app
4. after profile load, branch into default-workspace entry, workspace selection, or onboarding

Error Handling

1. AUTH.INVALID_CREDENTIALS means restart with corrected credentials
2. AUTH.MFA_SEND_COOLDOWN should disable resend until the cooldown expires
3. AUTH.MFA_CODE_INVALID should keep the same sessionId alive until the TTL ends
4. 4010 on the profile call usually means the access token was not stored or attached

Next Steps

1. Password Flow
2. Profile and Onboarding
3. Default Workspace and Membership