fastify-xadmin

Users Routes

Admin REST endpoints for listing, reading, updating, and deleting user accounts — GET /api/admin/users, GET/PATCH/DELETE /api/admin/users/:id.

Users Routes

CRUD endpoints for managing user accounts. All routes require the admin role configured at registration (default "superadmin").

Routes

GET    /api/admin/users        List all users
GET    /api/admin/users/:id    Get a single user
PATCH  /api/admin/users/:id    Update a user
DELETE /api/admin/users/:id    Delete a user

GET /api/admin/users

List all users in the system with optional filtering and pagination.

Usage

const response = await fetch("/api/admin/users?page=1&limit=20", {
  headers: { Authorization: `Bearer ${adminToken}` },
});
const { users, total, page, limit } = await response.json();

Query Parameters

Name	Type	Default	Description
`page`	`number`	`1`	Page number (1-indexed).
`limit`	`number`	`20`	Results per page.
`search`	`string`	—	Filter by name or email (case-insensitive).
`role`	`string`	—	Filter by role slug.
`tenantId`	`string`	—	Filter by tenant.

Response

{
  "users": [
    {
      "id": "usr_123",
      "email": "alice@example.com",
      "name": "Alice",
      "role": "admin",
      "tenantId": "tnt_456",
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

GET /api/admin/users/:id

Fetch a single user by their ID.

Usage

const response = await fetch(`/api/admin/users/${userId}`, {
  headers: { Authorization: `Bearer ${adminToken}` },
});
const user = await response.json();

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	User ID.

Response

{
  "id": "usr_123",
  "email": "alice@example.com",
  "name": "Alice",
  "role": "admin",
  "tenantId": "tnt_456",
  "createdAt": "2025-01-01T00:00:00.000Z"
}

PATCH /api/admin/users/:id

Partially update a user's profile or role.

Usage

const response = await fetch(`/api/admin/users/${userId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${adminToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ role: "member", name: "Alice Smith" }),
});
const updated = await response.json();

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	User ID.

Body Fields

Field	Type	Required	Description
`name`	`string`	No	Display name.
`email`	`string`	No	Email address.
`role`	`string`	No	Role slug to assign. Must be an existing role.
`tenantId`	`string`	No	Move user to a different tenant.

Response

Returns the updated user object.

DELETE /api/admin/users/:id

Permanently delete a user account.

Usage

await fetch(`/api/admin/users/${userId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${adminToken}` },
});

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	User ID to delete.

Response

{ "deleted": true, "id": "usr_123" }

AI Context

package: "@xenterprises/fastify-xadmin"
routes:
  - GET /api/admin/users — paginated user list with search/role/tenant filters
  - GET /api/admin/users/:id — single user record
  - PATCH /api/admin/users/:id — partial update (name, email, role, tenantId)
  - DELETE /api/admin/users/:id — permanent deletion
auth: all routes require the admin role set at plugin registration