Role-Based Access Control (RBAC)

AxilJS provides authorization middleware for implementing role-based access control (RBAC), permission-based access control, and resource ownership checks in TypeScript and Node.js applications.

These authorization checks can be combined with JWT authentication to protect routes based on the authenticated user's role, permissions, or ownership of a resource.

Role-Based Access#

Use requireRole() to restrict a route to one or more roles.

import { requireRole } from '@axiljs/auth'
 
app.delete(
  '/users/:id',
  authenticate(jwt),
  requireRole('admin'),
  handler
)
 
app.get(
  '/reports',
  authenticate(jwt),
  requireRole(['admin', 'manager']),
  handler
)

A single role can be provided as a string:

requireRole('admin')

Multiple allowed roles can be provided as an array:

requireRole(['admin', 'manager'])

The authenticated user must have an allowed role to access the protected route.

Permission-Based Access Control#

For more granular authorization, use requirePermission().

import { requirePermission } from '@axiljs/auth'
 
app.post(
  '/posts',
  authenticate(jwt),
  requirePermission('posts:create'),
  handler
)

Permissions can represent specific application capabilities, such as:

posts:create
posts:read
posts:update
posts:delete

This approach allows authorization rules to be defined around specific actions rather than relying only on broad user roles.

Wildcard Permissions#

Permission patterns can use wildcards.

requirePermission('admin:*')

The admin:* pattern matches permissions such as:

admin:read
admin:write
admin:delete

This can be useful when a role or user should have access to an entire permission namespace rather than a single operation.

Resource Ownership#

Use requireOwnership() when access should depend on whether the authenticated user owns the requested resource.

import { requireOwnership } from '@axiljs/auth'
 
app.get(
  '/users/:id/profile',
  authenticate(jwt),
  requireOwnership('id'),
  handler
)

The 'id' argument identifies the route parameter used for the ownership check.

For example, with:

/users/:id/profile

the middleware can use the id route parameter to determine whether the authenticated user owns the requested resource.

Administrators bypass the ownership check.

Combining Authentication and Authorization#

Authentication and authorization can be composed as middleware:

app.delete(
  '/users/:id',
  authenticate(jwt),
  requireRole('admin'),
  handler
)

The request first passes through JWT authentication and then through the role authorization check.

HTTP Request
     │
     ▼
authenticate(jwt)
     │
     ▼
Authenticated User
     │
     ▼
Authorization Check
     │
 ┌───┼─────────────────┐
 ▼   ▼                 ▼
Role Permission   Ownership
 │       │             │
 └───────┴─────────────┘
           │
           ▼
      Route Handler

This separation keeps authentication and authorization responsibilities distinct.

Choosing an Authorization Strategy#

Use role-based authorization when access is naturally grouped by roles:

requireRole('admin')

Use permission-based authorization when you need fine-grained control over individual operations:

requirePermission('posts:create')

Use ownership checks when access depends on the relationship between the authenticated user and a resource:

requireOwnership('id')

These mechanisms can be used independently or composed with JWT authentication to enforce application-specific access-control rules.

Common RBAC Patterns#

An administrator-only endpoint:

app.delete(
  '/users/:id',
  authenticate(jwt),
  requireRole('admin'),
  handler
)

An endpoint available to multiple roles:

app.get(
  '/reports',
  authenticate(jwt),
  requireRole(['admin', 'manager']),
  handler
)

A permission-protected endpoint:

app.post(
  '/posts',
  authenticate(jwt),
  requirePermission('posts:create'),
  handler
)

An ownership-protected endpoint:

app.get(
  '/users/:id/profile',
  authenticate(jwt),
  requireOwnership('id'),
  handler
)