# Managing roles

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

## Overview

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.

## Setup

Create the `roles` and `user_roles` tables, and apply `withPermissions` to the Role model and `withRoles` to the User model. The [Quick start](/docs/packages/permissions/quick-start#create-the-database-tables) shows each step.

## withRoles options

::::field-group

:::field{name="roleModel" type="() => RoleModel" required}
A function that returns the Role model class.
:::

:::field{name="pivotTable" type="string" required}
The name of the pivot table linking users to roles.
:::

:::field{name="pivotForeignKey" type="string"}
The foreign key column on the pivot table for the user. Defaults to Lucid's convention (`user_id`).
:::

:::field{name="pivotRelatedForeignKey" type="string"}
The foreign key column on the pivot table for the role. Defaults to Lucid's convention (`role_id`).
:::

::::

## Creating roles with permissions

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.

```ts
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](./managing-permissions) guide.

## Assigning roles to users

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

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

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

## Changing a user's roles

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

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

## Reading a user's roles

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

```ts
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.

## Aggregating permissions

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.

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