Roles Routes

Role-based access control management: role CRUD, the full permission catalog, per-role permission updates, and assigning/revoking roles on users. The permission catalog is the plugin's DEFAULT_PERMISSIONS plus any custom entries passed via the permissions option.

Routes

GET /api/admin/roles

Return all roles ordered by name, each with a userCount. Not paginated.

Response

{
  "success": true,
  "data": [
    { "id": "role_1", "name": "Admin", "description": "Full access", "permissions": ["admin:*"], "isDefault": false, "userCount": 3 }
  ]
}

POST /api/admin/roles

Create a role. Returns 201. When isDefault is true, any existing default role is cleared first.

Body Fields

GET /api/admin/roles/permissions

Return the full permission catalog (defaults + custom) from fastify.xAdmin.permissions.all.

{
  "success": true,
  "data": [
    { "id": "users:read", "resource": "users", "action": "read", "category": "User Management" }
  ]
}

GET /api/admin/roles/:id

Fetch a single role with userCount. Returns 404 when the role does not exist.

PUT /api/admin/roles/:id

Update a role. Body accepts name, description, isDefault (all optional). Setting isDefault: true clears the flag on all other roles.

DELETE /api/admin/roles/:id

Delete a role. Returns 404 when the role does not exist, and 409 (Cannot delete role with N assigned users) while any user still has the role.

PUT /api/admin/roles/:id/permissions

Replace a role's permission set.

Body Fields

Unknown permission ids are rejected with 400 (Invalid permissions: ...) — ids are validated against the catalog before any write.

POST /api/admin/roles/:id/assign

Assign a role to a user.

Body Fields

Returns 404 when the role or user does not exist. With the optional UserRole join table present, a duplicate assignment returns 409; without it, the user's role field is set to the role name.

POST /api/admin/roles/:id/revoke

Revoke a role from a user. Same body and 404 behavior as /assign. Without the UserRole join table, the user falls back to the default role (or "user").

AI Context

package: "@xenterprises/fastify-xadmin"
routes:
  - GET /api/admin/roles — all roles + userCount, ordered by name; not paginated
  - POST /api/admin/roles — create (name required; description, permissions[], isDefault); 201
  - GET /api/admin/roles/permissions — full permission catalog (defaults + custom)
  - GET /api/admin/roles/:id — single role; 404
  - PUT /api/admin/roles/:id — update name/description/isDefault
  - DELETE /api/admin/roles/:id — 404; 409 while users assigned
  - PUT /api/admin/roles/:id/permissions — body: permissions[] (required); 400 on unknown ids
  - POST /api/admin/roles/:id/assign — body: userId (required); 404; 409 duplicate
  - POST /api/admin/roles/:id/revoke — body: userId (required); 404
permissions: roles:read/create/update/delete/manage
notes: UserRole join table optional — falls back to user.role string; isDefault is exclusive

See Also

• Users Routes — change a user's role via PUT /users/:id/role
• fastify-xadmin — default permission catalog and fastify.xAdmin.permissions API
• Audit Log Routes — role changes are recorded