Users Routes

Full user administration. Successful writes invalidate the dashboard metrics and activeUsers caches, and every mutation is recorded in the audit log.

Routes

GET /api/admin/users

Paginated user list with search, filters, and sorting.

Query Parameters

Response

{
  "success": true,
  "data": [
    { "id": "usr_123", "email": "alice@example.com", "name": "Alice", "role": "admin", "status": "active", "lastLoginAt": "2026-07-20T08:00:00.000Z", "createdAt": "2026-01-01T00:00:00.000Z" }
  ],
  "meta": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

POST /api/admin/users

Create a user. Returns 201. Returns 409 (User with this email already exists) on duplicate email. New users get status: "active" and role: "user" unless specified.

Body Fields

GET /api/admin/users/:id

Fetch a single user, including suspension fields (suspendedAt, suspendedReason) and metadata. Returns 404 when the user does not exist.

PUT /api/admin/users/:id

Update a user. Body accepts name, email, avatar, metadata (all optional).

DELETE /api/admin/users/:id

Delete a user. Returns 404 when the user does not exist.

Query Parameters

hardDelete is a real boolean: the querystring schema coerces the value, so ?hardDelete=true arrives as boolean true and ?hardDelete=false as false. Any other value (or omitting the param) soft-deletes — the user's status is set to "deleted" and deletedAt is stamped, but the row remains.

Response: { "success": true, "data": null }. The audit entry records which mode was used.

PUT /api/admin/users/:id/role

Change a user's role. Returns 404 when the user does not exist.

Body Fields

The response includes previousRole, and the audit entry records both old and new roles.

POST /api/admin/users/:id/suspend

Suspend a user. Optional body field reason (string) is stored as suspendedReason. Sets status: "suspended" and suspendedAt.

POST /api/admin/users/:id/unsuspend

Re-activate a suspended user: sets status: "active" and clears suspendedAt/suspendedReason.

POST /api/admin/users/:id/reset-password

Trigger a password reset for the user. Returns 404 when the user does not exist. The response reports resetEmailSentAt; the audit entry records the trigger.

AI Context

package: "@xenterprises/fastify-xadmin"
routes:
  - GET /api/admin/users — paginated list; query: page, limit (1-100), sort (name/email/createdAt/lastLoginAt/role/status), order, search, role, status
  - POST /api/admin/users — create (email required); 201; 409 duplicate email
  - GET /api/admin/users/:id — single user incl. suspension fields; 404
  - PUT /api/admin/users/:id — update name/email/avatar/metadata
  - DELETE /api/admin/users/:id — soft delete (status=deleted + deletedAt); ?hardDelete=true (coerced boolean) hard-deletes; 404
  - PUT /api/admin/users/:id/role — body: role (required); 404
  - POST /api/admin/users/:id/suspend — body: reason?; sets status suspended
  - POST /api/admin/users/:id/unsuspend — clears suspension
  - POST /api/admin/users/:id/reset-password — trigger reset; 404
permissions: users:read/create/update/delete/manage
side-effects: writes audit-log entries; invalidate dashboard metrics + activeUsers caches

See Also

• Roles Routes — manage the roles assigned to users
• Impersonation Routes — log in as a user for support/debugging
• Tenants Routes — manage tenants users belong to
• Audit Log Routes — every user mutation is recorded