Security and Invitations

Overview

This guide covers the SYSTEM security-center actions that matter most after login: MFA setup, IP whitelist control, session cleanup, and invitation inbox handling. These flows are frequently implemented together because invited users often need to finish security setup before normal portal use.

Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. secure-channel support for encrypted mutations
4. an authenticator app if OTP MFA will be enabled

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
Authorization: Bearer <accessToken>
Content-Type: application/json

Step-by-Step Flow

1. Read current MFA state

API endpoint: GET /web/v1/system/security/mfa Use this to see which factors exist before showing setup or revoke actions.

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

{"code":"2000","message":"SUCCESS","data":[{"mfaMethod":{"code":"EMAIL","value":10011001,"label":"Email"},"isEnabled":true},{"mfaMethod":{"code":"OTP","value":10011002,"label":"OTP"},"isEnabled":false}]}

2. Set up and verify OTP MFA

API endpoints: POST /web/v1/system/security/mfa/otp/setup, POST /web/v1/system/security/mfa/otp/verify

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

{"code":"2000","message":"SUCCESS","data":{"secret":"JBSWY3DPEHPK3PXP","qrCodeUri":"otpauth://totp/SlaunchX:admin@example.com?...","issuer":"SlaunchX"}}

curl -X POST 'https://api.example.com/web/v1/system/security/mfa/otp/verify' \
  -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 '{"code":"482916"}'

{"status":204,"body":null}

3. Read and update the IP whitelist

API endpoints: GET /web/v1/system/security/ip-whitelist, POST /web/v1/system/security/ip-whitelist, POST /web/v1/system/security/ip-whitelist/enable

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

{"code":"2000","message":"SUCCESS","data":{"enabled":true,"entries":["192.168.1.0/24","10.0.0.1"]}}

curl -X POST 'https://api.example.com/web/v1/system/security/ip-whitelist' \
  -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 '{"entries":["203.0.113.10","198.51.100.0/24"]}'

{"code":"2000","message":"SUCCESS","data":{"enabled":true,"entries":["203.0.113.10","198.51.100.0/24"]}}

4. Inspect and clean up active sessions

API endpoints: GET /web/v1/system/security/sessions, POST /web/v1/system/security/sessions/terminate, POST /web/v1/system/security/sessions/terminate-all

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

{"code":"2000","message":"SUCCESS","data":[{"sessionId":"SESS...C_001","clientIp":"127.0.0.10","isCurrent":true},{"sessionId":"SESS...R_001","clientIp":"127.0.0.11","isCurrent":false}]}

5. Accept or decline invitations

API endpoints: GET /web/v1/system/profile/invitations, POST /web/v1/system/profile/invitations/{invitationBizId}/accept, POST /web/v1/system/profile/invitations/{invitationBizId}/decline

curl -X POST 'https://api.example.com/web/v1/system/profile/invitations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/accept' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"workspaceBizId":"WS_ACME_001","becameDefaultWorkspace":false,"nextAction":{"code":"ENTER_ACCEPTED_WORKSPACE","value":10050403,"label":"Enter accepted workspace"}}}

Decision Points

1. if OTP is already enabled, skip setup and offer revoke or backup-code actions
2. enable IP whitelist only after at least one valid entry exists
3. use single-session termination for one device and terminate-all for a broad cleanup
4. invitation acceptance may change the user's next route or default workspace

Error Handling

1. AUTH.MFA_CODE_INVALID means the setup session still exists but the code was wrong
2. AUTH.OTP_SETUP_SESSION_INVALID means the user must restart OTP setup
3. invitation accept can fail with WORKSPACE.INVITATION_EXPIRED or WORKSPACE.INVITATION_ALREADY_PROCESSED
4. whitelist mistakes can cause future login lockouts, so validate entries carefully

Next Steps

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