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

# Register

> Register a new user account with email/password or initial account setup.

# Register

LearnWay provides multiple ways to register a user account: traditional email and password registration, OTP-based signup, and initial account setup for social signups.

***

## Register with Password

Creates a new user profile with email, password, username, and an optional referral code. Upon successful registration, the user receives an initial session with JWT tokens and a generated on-chain wallet address.

### Endpoint

```http theme={null}
POST /api/v2/auth/register-with-password
```

### Request Headers

| Header         | Type     | Required | Description                |
| :------------- | :------- | :------- | :------------------------- |
| `Content-Type` | `string` | **Yes**  | Must be `application/json` |

### Request Body

| Field          | Type     | Required | Description                                                                              |
| :------------- | :------- | :------- | :--------------------------------------------------------------------------------------- |
| `email`        | `string` | **Yes**  | Valid user email address                                                                 |
| `username`     | `string` | **Yes**  | Unique username (3-30 alphanumeric and underscore characters)                            |
| `password`     | `string` | **Yes**  | Password (min 8 chars, at least 1 uppercase, 1 lowercase, 1 number, 1 special character) |
| `country`      | `string` | **Yes**  | ISO 2-letter country code (e.g. `US`, `NG`, `KE`)                                        |
| `referralCode` | `string` | No       | Referral code of the inviting user                                                       |

```json theme={null}
{
  "email": "john.doe@example.com",
  "username": "john_doe",
  "password": "SecurePassword123!",
  "country": "US",
  "referralCode": "LEARN2025"
}
```

### Response (201 Created)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "username": "john_doe",
    "role": "USER",
    "country": "US",
    "isEmailVerified": false,
    "totalXP": 0,
    "totalGems": 0,
    "walletAddress": "0x71C...3921",
    "badges": [],
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "expiresAt": "2026-08-22T22:00:00.000Z"
  },
  "message": "User registered successfully"
}
```

***

## Setup Account (Post-Social / Onboarding)

Used to finalize registration details (such as username, country, and interests) for users who initiated signup through social login.

### Endpoint

```http theme={null}
POST /api/v2/auth/setup-account
```

### Request Body

| Field          | Type     | Required | Description                                |
| :------------- | :------- | :------- | :----------------------------------------- |
| `email`        | `string` | **Yes**  | Verified email address from OAuth provider |
| `username`     | `string` | **Yes**  | Desired unique username                    |
| `country`      | `string` | **Yes**  | ISO 2-letter country code                  |
| `provider`     | `string` | **Yes**  | `google` or `apple`                        |
| `referralCode` | `string` | No       | Referral code                              |

```json theme={null}
{
  "email": "john.doe@gmail.com",
  "username": "johndoe_web3",
  "country": "NG",
  "provider": "google",
  "referralCode": "SUMMER2026"
}
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@gmail.com",
    "username": "johndoe_web3",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  },
  "message": "Account setup completed successfully"
}
```