Introduction
On this page
Permissions is a premium package that adds role-based access control to AdonisJS 7 apps. In this guide, you will learn:
- How Permissions differs from Bouncer
- How the permission system is structured
- What components are available
Overview
Section titled "Overview"AdonisJS ships with Bouncer, a low-level authorization layer that lets you express access checks as runtime functions. With Bouncer, you write abilities and policies that can inspect any condition: resource ownership, subscription status, time-based rules, or anything else. You write a function for each check.
Many applications do not need that level of flexibility. They need role-based access control (RBAC) with a static set of permissions: "editors can publish posts", "admins can manage users", "billing managers can issue refunds". Any user with the right permission can perform the action. The check does not depend on who owns a record or on other conditions.
Permissions is built for this use case. It sits on top of Bouncer and provides a type-safe API for defining permissions, assigning them to roles and users, and checking access. You define the permissions once in start/permissions.ts, and permissions.abilities() turns each one into a Bouncer ability.
Components
Section titled "Components"The package has these parts:
- Permission definitions declare the full set of capabilities your application supports using a resource/action pattern. You define them once and reference them everywhere.
- The Access class resolves a user's raw permissions against the master definition, handling aliases and inactive permissions. It provides
allowsanddenieschecks and supports token scoping. - The withPermissions mixin adds a JSON
permissionscolumn to any Lucid model (typically a Role model) with methods to give, sync, and revoke permissions. - The withRoles mixin adds a many-to-many relationship between a user model and a role model, with methods to assign, sync, and revoke roles. It aggregates permissions from all assigned roles.
These components compose together. Define your permissions, store them on roles using the withPermissions mixin, assign roles to users using the withRoles mixin, and check access using Bouncer abilities generated from your definitions.
- The
authorizemiddleware checks a permission on a route before the controller runs. - The
Guardcomponent shows part of an Inertia page (React or Vue) only to users who hold a permission.
Peer dependencies
Section titled "Peer dependencies"Permissions needs Node.js 24 or later.
@adonisjs/core^7.0.0required@adonisjs/bouncer^4.0.0required@adonisjs/lucid^22.0.0required@adonisjs/assembler^8.0.0indexPermissions hook, which writes the permission types for your frontend. Optional.