Permissions

The permissions package provides a declarative role-based permission system for AdonisJS. In this guide, you will learn:

• How the permissions package differs from Bouncer
• How the permission system is structured
• What components are available

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. This flexibility is powerful, but it means you write a function for every 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. No resource ownership checks, no complex conditions.

The permissions package 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 your permissions once, and the package generates Bouncer abilities automatically.

Components

The system is built around four components:

• 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.

Peer dependencies