Account Guide

Overview

The SYSTEM account domain begins after authentication and covers the user-controlled parts of the portal experience: profile data, onboarding decisions, security posture, session hygiene, and invitation inbox behavior. These calls are what turn a fresh JWT into a usable application session.

What This Domain Covers

1. own profile retrieval and update
2. onboarding and post-login routing decisions
3. password initialization for new or invited users
4. MFA, backup codes, IP whitelist, and session controls
5. invitation listing, acceptance, and decline flows

Common Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. secure-channel support for encrypted security mutations
4. a consistent understanding of the current workspace and invitation context

Shared Request Pattern

Profile and read-only security calls:

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

Sensitive mutations add a secure-channel header:

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

Core Endpoints

Profile

1. GET /web/v1/tenant/profile
2. POST /web/v1/tenant/profile/update
3. POST /web/v1/tenant/auth/password/init

Security

1. GET /web/v1/tenant/security/mfa
2. POST /web/v1/tenant/security/mfa/otp/setup
3. POST /web/v1/tenant/security/mfa/otp/verify
4. GET /web/v1/tenant/security/ip-whitelist
5. POST /web/v1/tenant/security/ip-whitelist
6. POST /web/v1/tenant/security/sessions/terminate

Invitations

1. GET /web/v1/tenant/profile/invitations
2. POST /web/v1/tenant/profile/invitations/{invitationBizId}/accept
3. POST /web/v1/tenant/profile/invitations/{invitationBizId}/decline

Typical Session Bootstrap

A newly authenticated SYSTEM UI usually follows this sequence:

1. fetch /web/v1/tenant/profile
2. fetch /web/v1/tenant/workspaces/mine
3. fetch /web/v1/tenant/profile/invitations when routing depends on pending invites
4. branch into app entry, workspace selection, create-workspace, or invitation handling

Decision Points

1. whether the user is entering as a normal returning admin or a newly invited account
2. whether the user still needs to initialize a password
3. whether MFA must be enabled before the app can continue
4. whether the user has an accessible default workspace
5. whether pending invitations should override the standard landing page

Error Handling

1. 4010 almost always means the JWT is missing, expired, or attached to the wrong portal ingress
2. profile update and security mutations can fail if the secure-channel context is missing
3. invitation actions can fail with conflict errors when the invitation is already processed or expired
4. onboarding logic should not assume that workspace data or invitation data is embedded in the profile payload
5. if session-related calls fail, retry after refreshing the access token before forcing a full logout

Recommended Guide Order

1. start with Profile and Onboarding
2. then implement Security and Invitations
3. connect the result to Workspace Guide

Next Steps

1. Profile and Onboarding
2. Security and Invitations
3. Workspace Guide
4. Auth Guide