Administration

User management endpoints for administrators. All endpoints require Admin or Overseer role.

Base Route: /api/admin
Authorization: Admin or Overseer role required

---

List Users

Returns a paginated list of all registered users.

GET /api/admin/users?page=1&pageSize=10&search=john

Query Parameters

Parameter	Type	Default	Constraints	Description
page	int	1	>= 1	Page number
pageSize	int	10	1–100 (clamped)	Results per page
search	string	null	Optional	Filter by email, first name, or last name

Response 200 OK

{
  "success": true,
  "message": null,
  "users": [
    {
      "id": "a1b2c3d4-e5f6-...",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "isEmailVerified": true,
      "createdAt": "2025-01-15T10:30:00Z",
      "roles": ["User"]
    }
  ],
  "totalCount": 42,
  "page": 1,
  "pageSize": 10
}

---

Update User

Modifies a user's profile and/or role assignments.

PUT /api/admin/users/{id}

Path Parameters

Parameter	Type	Description
id	string	User ID

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "roles": ["User", "Admin"]
}

Field	Type	Required	Description
firstName	string	No	Updated first name
lastName	string	No	Updated last name
roles	string[]	No	Complete role list to assign

Role Assignment Rules

• Admins cannot assign the Overseer role
• Only Overseer can promote users to Overseer
• Valid roles: User, Admin, Overseer

Response 200 OK

{
  "success": true,
  "message": "User updated.",
  "user": {
    "id": "a1b2c3d4-e5f6-...",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "isEmailVerified": true,
    "createdAt": "2025-01-15T10:30:00Z",
    "roles": ["User", "Admin"]
  }
}

---

Confirm User Email

Manually confirms a user's email address without requiring the verification code.

POST /api/admin/users/{id}/confirm-email

Path Parameters

Parameter	Type	Description
id	string	User ID

Response 200 OK

{
  "success": true,
  "message": "Email confirmed.",
  "user": { ... }
}

---

Delete User

Permanently removes a user account and all associated data.

DELETE /api/admin/users/{id}

Path Parameters

Parameter	Type	Description
id	string	User ID

Response 200 OK

{
  "success": true,
  "message": "User deleted.",
  "user": null
}

Cascade Effects

• All user's Sun Sources are deleted
• All Power Groups are deleted
• All associated MongoDB telemetry data is removed
• All sharing configurations are removed
• All KWh price history records are removed
• All weather data records are removed

---

Response Schema: UsersResponse

interface UsersResponse {
  success: boolean;
  message: string | null;
  users: UserDto[];
  totalCount: number;
  page: number;
  pageSize: number;
}

interface UserDto {
  id: string;
  email: string;
  firstName: string | null;
  lastName: string | null;
  isEmailVerified: boolean;
  createdAt: string; // ISO 8601
  roles: string[];
}

interface UserResponse {
  success: boolean;
  message: string | null;
  user: UserDto | null;
}