# createUser

## Overview

Creates a new user account with ACTIVE status, optionally assigns one or more roles, and provisions an IDP user with an auto-generated password. The initial password is returned in the response for the admin to communicate to the user.

## Modules Commands Used

- `user-management.createUser` — Creates a new user record in PENDING status
- `user-management.activateUser` — Transitions user to ACTIVE status
- `user-management.assignRoleToUser` — Assigns each selected role to the new user (called once per role)

## Exception Handling

| Error Code                | Source               | Description                                                              |
| ------------------------- | -------------------- | ------------------------------------------------------------------------ |
| USER_ALREADY_EXISTS       | createUser           | A user with the same email exists                                        |
| MISSING_REQUIRED_FIELD    | createUser           | Name or email is missing                                                 |
| INVALID_EMAIL             | createUser           | Email format is invalid                                                  |
| ROLE_NOT_FOUND            | assignRoleToUser     | One of the selected roles does not exist                                 |
| USER_NOT_FOUND            | assignRoleToUser     | The created user was not found (should not occur in normal flow)         |
| USER_NOT_ACTIVE           | assignRoleToUser     | The user is not in ACTIVE status (should not occur in normal flow)       |
| IDP provisioning failure  | idp.Client.createUser | IDP user creation failed. DB transaction is rolled back — no user record is created |