fastify-xauth-better
requireRole(roles)
Returns a preHandler that enforces global user role membership.
requireRole(roles)
Returns a preHandler middleware that checks request.user.role against an allowed-roles list. Responds with 403 Forbidden if the user's global role is not in the list. Must be preceded by requireAuth() (or a global prefix) so that request.user is already populated.
Signature
instance.requireRole(
roles: string | string[]
): (request: FastifyRequest, reply: FastifyReply) => Promise<void>
Params
| Name | Type | Required | Description |
|---|---|---|---|
roles | string | string[] | Yes | One or more allowed global role values (matched against User.role) |
Returns
A preHandler function to pass to a route's preHandler option.
Throws
401 Unauthorized—request.useris not set (auth middleware not applied first)403 Forbidden— user'sroleis not in the allowed list
Examples
Single role
const adminAuth = fastify.xauthbetter.get("admin");
fastify.get("/api/admin/dashboard", {
preHandler: [adminAuth.requireRole("admin")],
}, async (request) => {
return { user: request.user };
});
Multiple allowed roles
fastify.delete("/api/admin/users/:id", {
preHandler: [
adminAuth.requireAuth(),
adminAuth.requireRole(["admin", "superadmin"]),
],
}, async (request) => {
return { deleted: request.params.id };
});
See also
- requireAuth() — authenticate first before checking roles
- requireOrgRole(roles) — enforce org-scoped roles instead of global roles
AI Context
package: "@xenterprises/fastify-xauth-better"
method: fastify.xauthbetter.get(name).requireRole(roles)
use-when: Fastify preHandler factory that enforces global user role — returns 403 if user lacks the required role
usage: { preHandler: [auth.requireAuth(), auth.requireRole(['admin'])] }