Authentication

Role-Based Access Control (RBAC)

Implement role-based access control (RBAC), permission-based authorization, and resource ownership checks in TypeScript and Node.js applications with AxilJS.

3 min readUpdated DocumentationEdit this page
On this page7

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.

TypeScript
TS
1import { requireRole } from '@axiljs/auth'
2
3app.delete(
4  '/users/:id',
5  authenticate(jwt),
6  requireRole('admin'),
7  handler
8)
9
10app.get(
11  '/reports',
12  authenticate(jwt),
13  requireRole(['admin', 'manager']),
14  handler
15)

A single role can be provided as a string:

TypeScript
TS
requireRole('admin')

Multiple allowed roles can be provided as an array:

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

The authenticated user must have an allowed role to access the protected route. Roles are read from the JWT payload's role (string) or roles (array) claim. Without an authenticated user the middleware fails with 401; with the wrong role, 403.

Permission-Based Access Control

For more granular authorization, use requirePermission().

TypeScript
TS
1import { requirePermission } from '@axiljs/auth'
2
3app.post(
4  '/posts',
5  authenticate(jwt),
6  requirePermission('posts:create'),
7  handler
8)

Permissions can represent specific application capabilities, such as:

Output
TXT
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.

Permissions are read from the user's permissions array claim:

TypeScript
TS
const token = jwt.sign({ sub: '42', permissions: ['posts:create', 'posts:read'] })

Wildcard Permissions

Wildcards belong in the user's permissions, not in the requirePermission() argument. A user permission of admin:* satisfies any required permission in that namespace:

TypeScript
TS
// user.permissions = ['admin:*']
requirePermission('admin:read')   // allowed
requirePermission('admin:delete') // allowed

A user permission of * satisfies every check.

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.

TypeScript
TS
1import { requireOwnership } from '@axiljs/auth'
2
3app.get(
4  '/users/:id/profile',
5  authenticate(jwt),
6  requireOwnership('id'),
7  handler
8)

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

For example, with:

Output
TXT
/users/:id/profile

the middleware compares the id route parameter with the user's id (or sub) claim. The parameter name defaults to 'id'.

Users whose role is 'admin' (or whose roles include 'admin') bypass the ownership check.

Combining Authentication and Authorization

Authentication and authorization can be composed as middleware:

TypeScript
TS
1app.delete(
2  '/users/:id',
3  authenticate(jwt),
4  requireRole('admin'),
5  handler
6)

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

HTTP Request
authenticate(jwt)
Authenticated User
Authorization Check
RolePermissionOwnership
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:

TypeScript
TS
requireRole('admin')

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

TypeScript
TS
requirePermission('posts:create')

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

TypeScript
TS
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:

TypeScript
TS
1app.delete(
2  '/users/:id',
3  authenticate(jwt),
4  requireRole('admin'),
5  handler
6)

An endpoint available to multiple roles:

TypeScript
TS
1app.get(
2  '/reports',
3  authenticate(jwt),
4  requireRole(['admin', 'manager']),
5  handler
6)

A permission-protected endpoint:

TypeScript
TS
1app.post(
2  '/posts',
3  authenticate(jwt),
4  requirePermission('posts:create'),
5  handler
6)

An ownership-protected endpoint:

TypeScript
TS
1app.get(
2  '/users/:id/profile',
3  authenticate(jwt),
4  requireOwnership('id'),
5  handler
6)

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY