# Permissions

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

AdonisJS ships with [Bouncer](https://docs.adonisjs.com/guides/auth/authorization), 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

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.

## Peer dependencies

Permissions needs Node.js 24 or later.

::::field-group

:::field{name="@adonisjs/core" type="^7.0.0" required}
The AdonisJS framework core.
:::

:::field{name="@adonisjs/bouncer" type="^4.0.0" required}
The authorization layer. Permissions generates Bouncer abilities from your permission definitions.
:::

:::field{name="@adonisjs/lucid" type="^22.0.0" required}
The Lucid ORM for database operations and model mixins.
:::

:::field{name="@adonisjs/assembler" type="^8.0.0"}
Runs the `indexPermissions` hook, which writes the permission types for your frontend. Optional.
:::

::::

## Next steps

::card-group
:::card{title="Quick start" to="/docs/packages/permissions/quick-start"}
Define permissions, create roles and authorize a controller.
:::

:::card{title="Installation" to="/docs/get-started/installation#premium-packages"}
Point your project at the registry before you install Permissions.
:::
::
