User Management

List Users

GET /api/v1/users?limit=100&offset=0

List all users. Supports pagination.

Query parameters:

• limit (optional) — Max items to return (default 100, max 1000)
• offset (optional) — Items to skip (default 0)

Response: 200 OK — Paginated envelope

{
  "data": [
    {
      "id": "uuid",
      "username": "admin",
      "display_name": "",
      "role": "admin",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Note: password_hash is never included in responses.

Create User

POST /api/v1/users

Request body:

{
  "username": "jsmith",
  "password": "minimum-8-chars",
  "role": "operator",
  "display_name": "John Smith"
}

Validation:

• username and password are required
• role must be "admin", "engineer" or "operator" (defaults to "operator")
• password must be 8-72 characters (bcrypt limit)

Response: 201 Created (user object, no password_hash)

Error responses:

• 400 Bad Request — Validation failure
• 409 Conflict — Username already exists

Get User

GET /api/v1/users/{userID}

Get a single user by ID.

Response: 200 OK (user object)

Error: 404 Not Found

Update User

PUT /api/v1/users/{userID}

Update user fields (partial update). Does NOT update password (use PUT /auth/password for password changes).

Request body (all fields optional):

{
  "username": "jsmith",
  "role": "admin",
  "display_name": "Jane Smith",
  "is_active": false
}

Validation: role must be "admin", "engineer" or "operator".

Response: 200 OK (updated user object)

Error responses:

• 400 Bad Request — Invalid role
• 404 Not Found — User does not exist

Delete User

DELETE /api/v1/users/{userID}

Delete a user. Self-deletion is prevented.

Response: 204 No Content

Error responses:

• 400 Bad Request — Attempting to delete your own account
• 404 Not Found — User does not exist

Reset User Password (Admin)

PUT /api/v1/users/{userID}/password

Admin-only. Reset another user's password.

Request body:

{
  "password": "new-password-here"
}

Validation:

• password must be 8-72 characters (bcrypt limit)

Response: 204 No Content

Error responses:

• 400 Bad Request — Missing or invalid password
• 404 Not Found — User does not exist