# Users API

The Users module manages system user accounts for administrators, teachers, and staff.

## Model

```json
{
  "id": "uuid",
  "email": "user@school.edu",
  "name": "John Admin",
  "avatar": "https://...",
  "status": "active",
  "last_login": "2024-01-15T10:00:00Z",
  "teams": [...],
  "roles": [...],
  "team_id": "team-uuid",
  "created_at": "2024-01-01T00:00:00Z"
}
```

## Status Values

| Status | Description |
|--------|-------------|
| `active` | Active user account |
| `inactive` | Disabled account |
| `pending` | Awaiting activation |

## Endpoints

### List Users

**Endpoint:** `POST /api/users/list`

!!! note "Permission Required"
    Listing users requires appropriate role permissions.

### Get User by ID

**Endpoint:** `GET /api/users/:id`

### Create User

**Endpoint:** `POST /api/users`

!!! warning "Admin Only"
    User creation requires admin role.

**Request:**
```json
{
  "email": "newuser@school.edu",
  "name": "New User",
  "password": "initialPassword123",
  "role_ids": ["role-uuid"]
}
```

### Update User

**Endpoint:** `PUT /api/users/:id`

### Delete User

**Endpoint:** `DELETE /api/users/:id`

## Role Assignment

### Assign Role to User

**Endpoint:** `PUT /api/roles/:id/assign`

**Request:**
```json
{
  "user_ids": ["user-uuid-1", "user-uuid-2"]
}
```

### Remove Role from User

**Endpoint:** `PUT /api/roles/:id/remove`

**Request:**
```json
{
  "user_ids": ["user-uuid-1"]
}
```

## Team Assignment

### Assign User to Team

**Endpoint:** `PUT /api/teams/:id/assign`

**Request:**
```json
{
  "user_ids": ["user-uuid-1", "user-uuid-2"]
}
```

### Remove User from Team

**Endpoint:** `PUT /api/teams/:id/remove`

## Password Management

### Reset Password (Admin)

**Endpoint:** `POST /api/admin/reset-password/:userid`

Resets user password to the default value configured in environment.

### Change Password (Self)

**Endpoint:** `POST /api/auth/change-password`

See [Authentication](../authentication.md) for details.