This guide covers how to create roles, assign them to users, and check role membership. You will learn how to:

  • Configure the withRoles mixin
  • Create roles and assign permissions to them
  • Assign, sync, and revoke roles on users
  • Aggregate permissions from a user's roles

Roles are the recommended way to manage permissions. Instead of assigning individual permissions to each user, you create roles like "editor", "admin", or "billing manager", assign permissions to those roles, and then assign roles to users. When a user's responsibilities change, you update their role assignments rather than editing individual permissions.

Permissions provides two mixins for this workflow:

  • withPermissions goes on the Role model and adds a JSON column for storing permission strings.
  • withRoles goes on the User model and adds a many-to-many relationship to the Role model through a pivot table.

Create the roles and user_roles tables, and apply withPermissions to the Role model and withRoles to the User model. The Quick start shows each step.

roleModel() => RoleModelrequired
A function that returns the Role model class.
pivotTablestringrequired
The name of the pivot table linking users to roles.
pivotForeignKeystring
The foreign key column on the pivot table for the user. Defaults to Lucid's convention (user_id).
pivotRelatedForeignKeystring
The foreign key column on the pivot table for the role. Defaults to Lucid's convention (role_id).

Create a role and assign permissions to it. Use permissions.getKey() for type-safe permission keys. Your editor will autocomplete the available keys and catch typos at compile time.

import { permissions } from '#start/permissions'

const editor = await Role.create({ name: 'editor' })
await editor.givePermissions([
  permissions.getKey('product.create'),
  permissions.getKey('product.update'),
])

const admin = await Role.create({ name: 'admin' })
await admin.syncPermissions(permissions.active())

For a full reference on managing the permissions column (giving, syncing, revoking), see the Managing permissions guide.

You can pass role instances or role IDs to all assignment methods.

await user.assignRole(editor)
await user.assignRoles([editor, moderatorRole])

assignRole and assignRoles skip roles the user already holds. Other roles stay assigned.

syncRoles replaces the user's roles with the list you pass. revokeRole and revokeRoles remove the roles you pass.

await user.syncRoles([admin])
await user.revokeRole(editor)
await user.revokeRoles([editor, moderatorRole])

hasRole compares the name you pass with the name column of each of the user's roles. getRoles returns the roles themselves.

await user.hasRole('editor') // true or false
const roles = await user.getRoles()

The first call to getRoles loads the roles and keeps them on the model. Later calls, and calls after a preload('roles'), return that list without a query. Roles you assign after that show up when you fetch the user again.

The getPermissions method on the user collects permissions from all assigned roles into a single deduplicated array. This is the method used by the Access class and Bouncer abilities to determine what a user can do.

const allPermissions = await user.getPermissions()
// Combines permissions from all roles