Registration Flow

Overview

Use this guide when a SYSTEM deployment exposes self-registration for internal operators or pilot admins. The repo currently publishes SYSTEM password-init docs but not dedicated SYSTEM register endpoint pages, so the registration sequence below documents the internal portal pattern used by teams that enable it.

Prerequisites

1. confirmation that SYSTEM self-registration is enabled in the target deployment
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. a secure-channel session for encrypted request bodies
4. a stable X-Client-Hash
5. access to the user's email inbox

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 registration

API endpoint: POST /web/v1/tenant/auth/register/initiate Create a short-lived registration session after validating the email and basic account attributes.

curl -X POST 'https://api.example.com/web/v1/tenant/auth/register/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":"new-admin@example.com","accountName":"New System Admin"}'

{"code":"2000","message":"SUCCESS","data":{"sessionId":"reg_abc123","email":"new-admin@example.com","expiresIn":600}}

2. Verify the email challenge

API endpoint: POST /web/v1/tenant/auth/register/verify Confirm inbox ownership for the active registration session.

curl -X POST 'https://api.example.com/web/v1/tenant/auth/register/verify' \
  -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":"reg_abc123","code":"482916"}'

{"code":"2000","message":"SUCCESS","data":{"sessionId":"reg_abc123","verified":true,"verifiedAt":"2026-03-29T08:10:00Z"}}

3. Complete registration

API endpoint: POST /web/v1/tenant/auth/register/complete Finalize the account after email verification succeeds.

curl -X POST 'https://api.example.com/web/v1/tenant/auth/register/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":"reg_abc123","accountName":"New System Admin","defaultLanguage":"en","defaultTimezone":"America/Los_Angeles"}'

{"code":"2000","message":"SUCCESS","data":{"accountBizId":"ACC_SYS_099","email":"new-admin@example.com","status":"ACTIVE","passwordInitialized":false}}

4. Initialize the password when registration completes without one

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":"new-admin@example.com","status":10010202}}

Decision Points

1. some SYSTEM environments disable self-registration and require admin-assisted onboarding
2. some deployments set the password during register/complete, others require password/init
3. approval workflows may block login even after registration completes
4. invitation-based onboarding may send the user to invitation acceptance rather than generic onboarding

Error Handling

1. expired registration sessions should restart from initiate
2. duplicate email attempts should surface a targeted message instead of a generic failure
3. throttle resend and verify actions to avoid email-delivery lockouts
4. if password/init fails, let the user restart only the password portion

Next Steps

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