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

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.

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 allows and denies checks and supports token scoping.
  • The withPermissions mixin adds a JSON permissions column 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 authorize middleware checks a permission on a route before the controller runs.
  • The Guard component shows part of an Inertia page (React or Vue) only to users who hold a permission.

Permissions needs Node.js 24 or later.

@adonisjs/core^7.0.0required
The AdonisJS framework core.
@adonisjs/bouncer^4.0.0required
The authorization layer. Permissions generates Bouncer abilities from your permission definitions.
@adonisjs/lucid^22.0.0required
The Lucid ORM for database operations and model mixins.
@adonisjs/assembler^8.0.0
Runs the indexPermissions hook, which writes the permission types for your frontend. Optional.

Quick start

Define permissions, create roles and authorize a controller.

Installation

Point your project at the registry before you install Permissions.