> For the complete documentation index, see [llms.txt](https://qbits-organization.gitbook.io/buildwise-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qbits-organization.gitbook.io/buildwise-doc/authentication/accounts-management.md).

# Accounts Management

### Register New Account

Creates a new user account with email verification capability.

**Endpoint:** `POST /api/v1/auth/register`

**Request Body:**

```json
{
  "phoneNumber": "+255745051251",
  "password": "Password@123",
  "email": "user@example.com",
  "verificationChannel": "EMAIL"
}
```

**Password Requirements:**

* Minimum 8 characters
* At least one uppercase letter
* At least one lowercase letter
* At least one digit
* At least one special character (@$!%\*?\&#)

**Verification Channels:**

* `EMAIL` - Email-based OTP verification
* `SMS` - SMS-based OTP verification
* `WHATSAPP` - WhatsApp-based verification
* `EMAIL_AND_SMS` - Multi-channel verification
* `ALL_CHANNELS` - All available verification methods

**Response Codes:**

* `201` - Account created successfully
* `400` - User already exists or invalid data
* `422` - Request validation failed

**Success Response:**

```json
{
  "success": true,
  "httpStatus": "CREATED",
  "message": "User account created successful, please verify your email",
  "action_time": "2025-05-27T14:11:37.143039",
  "data": null
}
```

### Account Login

Authenticates users using email, phone number, or username credentials.

**Endpoint:** `POST /api/v1/auth/login`

**Request Body:**

```json
{
  "phoneEmailOrUserName": "user@example.com",
  "password": "Password@123"
}
```

**Authentication Flow:**

1. User provides credentials (email/phone/username + password)
2. System validates credentials against stored data
3. Verifies account activation status
4. Returns JWT tokens for authenticated session

**Response Codes:**

* `200` - Authentication successful
* `401` - Invalid credentials
* `403` - Account not verified
* `404` - User not found

**Success Response:**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Account login successful",
  "action_time": "2025-05-27T14:11:37.143039",
  "data": {
    "userData": {
      "id": "c83ed935-807d-4148-9a34-c4d701ddcfe0",
      "userName": "user123",
      "email": "user@example.com",
      "phoneNumber": "+255745051251",
      "isVerified": true,
      "roles": [{"roleName": "ROLE_NORMAL_USER"}]
    },
    "accessToken": "eyJhbGciOiJIUzM4NCJ9...",
    "refreshToken": "eyJhbGciOiJIUzM4NCJ9..."
  }
}
```

### Get All Users

Retrieves a list of all registered users in the system.

**Endpoint:** `GET /api/v1/auth/all-users`

**Authentication:** Required (Bearer token)

**Response Codes:**

* `200` - Users retrieved successfully
* `401` - Authentication required
* `403` - Insufficient permissions

**Success Response:**

```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "All users retrieved successfully",
  "action_time": "2025-05-27T14:11:37.143039",
  "data": [
    {
      "id": "c83ed935-807d-4148-9a34-c4d701ddcfe0",
      "phoneNumber": "+255745051250",
      "userName": "joshuasimon656",
      "email": "joshuasimon656@gmail.com",
      "locked": false,
      "twoFactorEnabled": false,
      "createdAt": "2025-05-27T13:17:56.037699",
      "editedAt": "2025-05-27T13:17:56.038215",
      "isVerified": true,
      "isEmailVerified": true,
      "roles": [{"roleName": "ROLE_NORMAL_USER"}]
    }
  ]
}
```

### Get User by ID

Retrieves detailed information for a specific user account.

**Endpoint:** `GET /api/v1/auth/single-user/{userId}`

**Path Parameters:**

* `userId` (UUID) - Unique identifier of the user account

**Authentication:** Required (Bearer token)

**Response Codes:**

* `200` - User details retrieved successfully
* `401` - Authentication required
* `404` - User not found