Password Flow

Overview

SYSTEM password operations cover first-time password setup, forgot-password recovery, and authenticated password change. The published SYSTEM docs include forgot, reset, init, and change, with secure-channel encryption on the write operations.

Prerequisites

1. X-PORTAL-ACCESS-CODE: <system-portal-code>
2. secure-channel support for encrypted request bodies
3. X-Client-Hash for pre-login flows
4. Turnstile token support for forgot-password
5. a JWT for authenticated change-password

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

Authenticated change-password adds:

Authorization: Bearer <accessToken>

Forgot Password Flow

1. Start recovery

API endpoint: POST /web/v1/tenant/auth/password/forgot The published SYSTEM contract sends a reset link/token rather than a separate password-OTP API.

curl -X POST 'https://api.example.com/web/v1/tenant/auth/password/forgot' \
  -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 'X-Turnstile-Token: <turnstile-token>' \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","turnstileToken":"<turnstile-token>"}'

{"code":"2000","message":"SUCCESS","data":{"success":true,"message":"If the email exists, a reset link will be sent"}}

2. Capture the reset token from the email link

API endpoint: no separate API call is currently published The frontend should extract the token and move directly to reset.

{"tokenSource":"email-link","token":"reset-token-xxx"}

3. Reset the password

API endpoint: POST /web/v1/tenant/auth/password/reset

curl -X POST 'https://api.example.com/web/v1/tenant/auth/password/reset' \
  -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 '{"token":"reset-token-xxx","newPassword":"NewP@ssw0rd!"}'

{"code":"2000","message":"SUCCESS","data":{"success":true,"message":"Password reset successful"}}

Change Password Flow

4. Change password inside an authenticated session

API endpoint: POST /web/v1/tenant/auth/password/change

curl -X POST 'https://api.example.com/web/v1/tenant/auth/password/change' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'X-Secure-Channel-Session-Id: <secure-channel-session-id>' \
  -H 'Content-Type: application/json' \
  -d '{"currentPassword":"OldP@ss!","newPassword":"NewP@ssw0rd!"}'

{"code":"2000","message":"SUCCESS","data":{"success":true,"message":"Password changed successfully"}}

First-Time Password Initialization

5. Initialize a password for a new or invited account

API endpoint: POST /web/v1/tenant/auth/password/init

curl -X POST 'https://api.example.com/web/v1/tenant/auth/password/init' \
  -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":"init-session-xxx","password":"NewP@ssw0rd!"}'

{"code":"2000","message":"SUCCESS","data":{"bizId":"ACC_USR_00000001","email":"user@example.com","status":10010202}}

Decision Points

1. use forgot plus reset when the user cannot authenticate
2. use change when the user is already logged in and knows the current password
3. use init when the account exists but has not set a password yet
4. do not expect a dedicated forgot-password OTP verification endpoint in current SYSTEM docs

Error Handling

1. REQUEST.RATE_LIMITED on forgot-password should disable retry until the window resets
2. AUTH.PASSWORD_RESET_TOKEN_INVALID means the token is expired, reused, or wrong
3. AUTH.CURRENT_PASSWORD_INCORRECT should stay in the change-password form without logout
4. validation failures often mean the secure-channel header or encrypted body is missing

Next Steps

1. Login Flow
2. Security and Invitations
3. Profile and Onboarding