Auth Guide

Overview

The SYSTEM auth domain covers every pre-login and session-establishment flow used by administrators and internal operators. In practice, a full auth journey usually combines secure-channel bootstrap, an auth endpoint under /web/v1/tenant/auth/*, and one or more follow-up account calls once JWT tokens are issued.

Portal-Specific Context

SYSTEM is a web-chain portal. Pre-login calls do not require a JWT, but they do require the portal ingress header and usually an encrypted request body carried over a secure-channel session.

Common Prerequisites

1. valid TENANT portal access code
2. a stable X-Client-Hash generated by the frontend session
3. secure-channel bootstrap for endpoints that accept encrypted bodies
4. support for storing accessToken and refreshToken

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
X-Client-Hash: <browser-fingerprint>
Content-Type: application/json

Add this header for encrypted request bodies:

X-Secure-Channel-Session-Id: <secure-channel-session-id>

Add this header after login succeeds:

Authorization: Bearer <accessToken>

Secure-Channel Bootstrap

Use these public endpoints before sending encrypted auth payloads:

1. GET /web/v1/secure-channel/public-key
2. POST /web/v1/secure-channel/session
3. POST /web/v1/secure-channel/session/close

This path is notable because it is not namespaced under /web/v1/tenant/, even though it is required by SYSTEM login, password, and some account-security flows.

Primary Sub-Flows

1. Login

Use Login Flow when the user already has credentials.

Core calls:

1. POST /web/v1/tenant/auth/login/initiate
2. POST /web/v1/tenant/auth/login/mfa/send
3. POST /web/v1/tenant/auth/login/complete

Outputs:

1. login session ID
2. selected MFA method
3. accessToken and refreshToken

2. Registration

Use Registration Flow when SYSTEM self-registration is enabled for a controlled deployment or internal onboarding program.

Typical stages:

1. create a registration session
2. verify email ownership
3. complete account creation
4. initialize a password when required

3. Password Lifecycle

Use Password Flow for recovery, first-time setup, and authenticated password rotation.

Core calls:

1. POST /web/v1/tenant/auth/password/forgot
2. POST /web/v1/tenant/auth/password/reset
3. POST /web/v1/tenant/auth/password/init
4. POST /web/v1/tenant/auth/password/change

Decision Points

1. whether the entry flow is public, invite-driven, or admin-assisted
2. whether the deployment requires secure-channel encryption at the gateway
3. whether MFA is email-based, OTP-based, or satisfied by backup code
4. whether the account is fully active or blocked by pending approval
5. whether the next route is onboarding, workspace selection, or security setup

Error Handling

Common auth failures usually come from transport context rather than business logic:

1. 4010 or auth-specific credential errors when the email, password, code, or session ID is invalid
2. 4000 validation errors when encrypted bodies are malformed or contain unknown fields
3. rate-limit responses on login, MFA send, forgot-password, and password change/reset flows
4. secure-channel failures when the public key, session ID, or encrypted body is stale
5. portal mismatch issues when the request does not arrive through SYSTEM ingress

Implementation Notes

1. treat pre-login session IDs as short-lived and single-purpose
2. keep the same X-Client-Hash across initiate, MFA, and complete steps
3. do not decode the JWT for profile data; fetch /web/v1/tenant/profile instead
4. refresh expired access tokens through the refresh-token endpoint rather than replaying the login flow

Next Steps

1. Login Flow
2. Registration Flow
3. Password Flow
4. Account Guide