> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Management Overview

> Complete guide to user registration, authentication, and profile management

## Introduction

The user management system provides comprehensive functionality for onboarding, authenticating, and managing user accounts in a multi-tenant environment. All user operations support both international and US-specific configurations through environment routing.

<Note>
  All endpoints require the `x-client-key` header. For US environment routing, include `x-us-env: true` header or `region=us` query parameter.
</Note>

## User Lifecycle

Understanding the complete user journey helps you implement the right flows at the right time:

```mermaid theme={null}
graph LR
    A[New User] --> B[Email Verification]
    B --> C[Phone Verification]
    C --> D[Personal Details]
    D --> E[Address Information]
    E --> F[Consent Collection]
    F --> G[Registered User]
    G --> H[KYC Verification]
    H --> I[Active User]
    I --> J[Profile Management]
```

### Lifecycle Stages

<CardGroup cols={2}>
  <Card title="Registration" icon="user-plus" href="/guides/user/registration">
    Multi-step onboarding process with email/phone verification and KYC data collection
  </Card>

  <Card title="Consent Management" icon="clipboard-check" href="/guides/consent/overview">
    GDPR/CCPA-compliant consent tracking collected during registration with immutable audit trails
  </Card>

  <Card title="Authentication" icon="lock" href="/guides/user/authentication">
    Secure login with optional OTP for enhanced security
  </Card>

  <Card title="Verification" icon="shield-check">
    Identity verification process with status tracking (UNVERIFIED → PENDING → VERIFIED)
  </Card>

  <Card title="Profile Management" icon="user-gear" href="/guides/user/profile">
    View and update user information, settings, and verification status
  </Card>
</CardGroup>

<Info>
  **Consent Collection**: Step 4 requires creating a formal consent record via the [Consent Management API](/guides/consent/overview) before address submission. Pass the `onboardingId` to establish comprehensive regulatory compliance (GDPR, CCPA, E-Sign Act) with complete audit trails. After registration finalizes (Step 5 or 6), link the consent to the `userId` (Step 7). This is essential before users can access features like card issuance or wallet delegation.
</Info>

## Registration Flow

The registration process follows a sequential 7-step flow that collects required KYC information:

<Steps>
  <Step title="Email Verification">
    Send verification code to user's email address and verify before proceeding
  </Step>

  <Step title="Phone Verification">
    Send SMS verification code to user's phone number and verify
  </Step>

  <Step title="Personal Details">
    Collect name, date of birth, nationality, and SSN (US users only)
  </Step>

  <Step title="Consent Collection">
    Create formal consent record using the [Consent Management API](/guides/consent/overview) by passing the `onboardingId`. This is required for regulatory compliance (GDPR, CCPA, E-Sign Act) and must be completed before address submission.
  </Step>

  <Step title="Physical Address">
    Collect residential address. This step finalizes registration for non-US users or US users with same mailing address, returning `userId` and `accessToken`.
  </Step>

  <Step title="Mailing Address (Optional)">
    For US users only with different mailing address. This step finalizes registration and returns `userId` and `accessToken`.
  </Step>

  <Step title="Link Consent to User">
    After registration finalizes (Step 5 or 6), link the consent set to the `userId` using `PATCH /v2/consent/onboarding/{consentSetId}`.
  </Step>
</Steps>

<Info>
  The registration flow returns an `onboardingId` after email verification that must be passed through each subsequent step to maintain session continuity.
</Info>

```mermaid theme={null}
sequenceDiagram
    participant Client as Frontend/Client
    participant API as Backend/API

    Note over Client,API: Step 1: Email Verification
    Client->>API: POST /v1/auth/register/email/send
    API-->>Client: 200 OK (Email sent)
    Client->>API: POST /v1/auth/register/email/verify<br/>{code, email, password}
    API-->>Client: 200 OK<br/>{onboardingId}

    Note over Client,API: Step 2: Phone Verification
    Client->>API: POST /v1/auth/register/phone/send<br/>{onboardingId, phone}
    API-->>Client: 200 OK (SMS sent)
    Client->>API: POST /v1/auth/register/phone/verify<br/>{onboardingId, code}
    API-->>Client: 200 OK

    Note over Client,API: Step 3: Personal Details
    Client->>API: POST /v1/auth/register/personal-details<br/>{onboardingId, name, DOB, nationality, SSN*}
    API-->>Client: 200 OK

    Note over Client,API: Step 4: Consent Collection
    Client->>API: POST /v2/consent/onboarding<br/>{onboardingId, policy, consents[]}
    API-->>Client: 200 OK<br/>{consentSetId}

    Note over Client,API: Step 5: Physical Address (Finalizes Registration)
    Client->>API: POST /v1/auth/register/address<br/>{onboardingId, address, city, zip, state}
    API-->>Client: 200 OK<br/>{userId, accessToken, user}

    Note over Client,API: Step 6: Mailing Address (US only, if needed)
    Client->>API: POST /v1/auth/register/mailing-address<br/>{onboardingId, mailingAddress}
    API-->>Client: 200 OK<br/>{userId, accessToken, user}

    Note over Client,API: Step 7: Link Consent to User
    Client->>API: PATCH /v2/consent/onboarding/{consentSetId}<br/>{userId}
    API-->>Client: 200 OK<br/>{linked consent set}

    Note over Client: Registration complete with consent audit trail<br/>Access token valid for 6 hours<br/>SSN* required for US users only
```

## Authentication Methods

The platform supports multiple authentication patterns for different use cases:

### Standard Login

Direct username/password authentication for registered users:

```bash theme={null}
POST /v1/auth/login
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}
```

**API Reference:** [`POST /v1/auth/login`](/api-reference/auth/login)

**Returns:** Access token valid for 6 hours

### OTP-Enhanced Login

For users with OTP enabled, an additional verification step is required:

1. Check `isOtpRequired` from login response
2. Request OTP code via [`POST /v1/auth/login/otp`](/api-reference/auth/login-otp)
3. Submit login credentials with `otpCode` field

<Warning>
  OTP codes are time-sensitive. Complete the OTP flow within the code expiration window (typically 5-10 minutes).
</Warning>

### OAuth 2.0 Integration

For third-party applications, OAuth 2.0 with PKCE provides delegated authorization:

* Full OAuth flow documentation: [OAuth 2.0 Guide](/guides/oauth)
* Supports authorization code flow with PKCE
* Refresh token support for long-lived sessions

See the [Authentication Guide](/guides/user/authentication) for detailed implementation patterns.

## Verification States

Users progress through verification states as they complete identity checks:

| State          | Description                             | Actions Available                             |
| -------------- | --------------------------------------- | --------------------------------------------- |
| **UNVERIFIED** | Initial state after registration        | Limited account access, verification required |
| **PENDING**    | Verification submitted, awaiting review | Full functionality may be restricted          |
| **VERIFIED**   | Identity confirmed                      | Full account access                           |
| **REJECTED**   | Verification failed                     | Contact support, may resubmit                 |

<Tip>
  Check verification status using [`GET /v1/user`](/api-reference/user/get-user) or [`GET /v1/user/verification`](/api-reference/user/verification) before performing operations that require verified users.
</Tip>

## Profile Management

Once registered, users can manage their account information:

### Available Operations

* **View Profile**: Get complete user details including verification status
* **Update Settings**: Modify account preferences and security settings
* **Check Verification**: Monitor KYC verification progress
* **Session Management**: Login, logout, and token refresh

### User Information Structure

```json theme={null}
{
  "id": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebb",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-01",
  "phoneNumber": "7400846282",
  "phoneCountryCode": "+44",
  "verificationState": "VERIFIED",
  "addressLine1": "23 Werrington Bridge Rd",
  "city": "Peterborough",
  "zip": "PE6 7PP",
  "countryOfResidence": "GB",
  "countryOfNationality": "GB"
}
```

## Security Considerations

### Password Requirements

While specific requirements may vary by environment configuration, follow these best practices:

* Minimum 8 characters
* Include uppercase and lowercase letters
* Include numbers and special characters
* Avoid common passwords or dictionary words

### Token Management

Access tokens are returned in two scenarios:

1. **After successful login**: Use for immediate API access
2. **After completing registration**: Initial authentication for new users

<Note>
  Access tokens expire after 6 hours. Implement token refresh logic or require re-authentication for long-running sessions.
</Note>

### Multi-Factor Authentication

OTP (One-Time Password) provides an additional security layer:

* Sent via SMS to registered phone number
* Time-limited codes
* Required for sensitive operations when enabled

## Regional Configurations

The API supports region-specific flows and requirements:

### International Environment

* Standard KYC requirements
* Physical address only (no mailing address)
* Country-specific field validation

### US Environment

Access via `x-us-env: true` header or `region=us` parameter:

* SSN (Social Security Number) required
* US state field mandatory
* Optional separate mailing address
* Enhanced compliance requirements

<Warning>
  US-specific fields (SSN, usState, mailing address) are required only when `countryOfResidence = "US"`. Validation will fail if these are missing for US users.
</Warning>

## Error Handling

Common error scenarios and resolutions:

<AccordionGroup>
  <Accordion title="Email Already Registered">
    **Error**: Email address already exists in the system

    **Resolution**: User should login instead of registering, or use password recovery if forgotten
  </Accordion>

  <Accordion title="Invalid Verification Code">
    **Error**: Email or phone verification code is incorrect or expired

    **Resolution**: Request a new verification code and try again within the expiration window
  </Accordion>

  <Accordion title="Missing Required Fields">
    **Error**: Required fields missing for user's country of residence

    **Resolution**: Ensure SSN and usState are provided for US users, validate all required fields based on countryOfResidence
  </Accordion>

  <Accordion title="Token Expired">
    **Error**: Access token or onboarding session expired

    **Resolution**: For onboarding, restart the registration flow. For access tokens, re-authenticate the user
  </Accordion>
</AccordionGroup>

## Quick Start Guide

Get started with user management in 3 steps:

<Steps>
  <Step title="Register New User">
    Follow the [Registration Guide](/guides/user/registration) to onboard new users with complete KYC data collection
  </Step>

  <Step title="Authenticate User">
    Implement login flows using the [Authentication Guide](/guides/user/authentication) with optional OTP support
  </Step>

  <Step title="Manage Profile">
    Access and update user information using the [Profile Management Guide](/guides/user/profile)
  </Step>
</Steps>

## Related Resources

<CardGroup cols={2}>
  <Card title="Registration Guide" icon="user-plus" href="/guides/user/registration">
    Step-by-step registration implementation with code examples
  </Card>

  <Card title="Consent Management" icon="clipboard-check" href="/guides/consent/overview">
    GDPR/CCPA-compliant consent tracking and audit trails
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/guides/user/authentication">
    Login flows, OTP, and session management
  </Card>

  <Card title="Profile Management" icon="user-gear" href="/guides/user/profile">
    View and update user information
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Complete endpoint documentation
  </Card>
</CardGroup>

## Next Steps

* [Complete Registration Flow →](/guides/user/registration)
* [Set Up Consent Management →](/guides/consent/overview)
* [Implement Authentication →](/guides/user/authentication)
* [Manage User Profiles →](/guides/user/profile)