Users API
List and view users by role (customers, staff, admins). Used by admin and staff dashboards. All routes require Authorization: Bearer <access_token>. Base path: <API_BASE_URL>/users. Access is controlled by role and permissions (see RBAC in Auth).
List by role
Returns all customers. Allowed: admin, or staff with permission view_customers. Response: {"customers": [...]}. Each item includes id, email, first_name, last_name, phone, is_active, is_verified, phone_verified, roles, created_at, and minimal customer_profile / staff_profile / admin_profile.
Returns all staff. Allowed: admin, or staff with permission manage_staff. Response: {"staff": [...]}.
Create a new staff user. Admin only. Body: email, password, first_name, last_name, department_id (ID of an active department; see Departments API), job_title, optional phone. Employee ID is auto-generated (format BBA+YY+DD+seq, e.g. BBA2610001). Returns full profile (201). 409 if email already exists.
Returns all admins. Allowed: admin only. Response: {"admins": [...]}.
Search customers (dedicated route)
Dedicated search for customers. Search by email, phone, first name, last name, or recipient name (customer profile). Query params: q (search term; empty returns []), limit (optional, default 50, max 100). Allowed: admin, or staff with permission view_customers. Response: {"customers": [...]} (same shape as GET /users/customers). Base path: <API_BASE_URL>/search.
View a specific user
Returns full profile for one user (customer, staff, or admin). user_id in the path is the user’s UUID (not an integer). Admin can view any user. Staff with view_customers can view customers only. Staff with manage_staff can view staff only. Response shape matches GET /profile (full profile with customer_profile, staff_profile, admin_profile as applicable). 404 if user not found; 403 if caller is not allowed to view that user.
Update a staff user. Admin only. Body: optional first_name, last_name, phone, employee_id, department_id (ID of an active department), job_title. Returns full profile. 400 if user is not staff. 409 if phone or employee_id already in use by another user.
Permanently delete a user. Admin only. Cascades to profiles and role assignments. 404 if user not found.
Deactivate or reactivate user
Uses is_active: ban sets it to false, unban sets it to true. Admin only.
Set user is_active to false. User cannot log in. Returns {"message": "User banned", "user_id": number}. 404 if user not found.
Set user is_active to true. Returns {"message": "User unbanned", "user_id": number}. 404 if user not found.
Common responses
401 if missing or invalid token. 403 if authenticated but lacking required role or permission (body may include required_roles or required_permissions). 404 if the requested user does not exist.