# Managing permissions

This guide covers assigning permissions directly to models. You will learn how to:

- Apply the `withPermissions` mixin to a User model
- Give, sync, and revoke direct permissions
- Combine direct permissions with role-based permissions

## Overview

The recommended approach is to manage permissions through [roles](./managing-roles). However, some applications need to assign extra permissions to specific users outside of their role. For example, a user might have the "editor" role but also need the `billing.refund` permission that editors do not normally have.

The `withPermissions` mixin can be applied to any Lucid model, including your User model, to store permissions directly as a JSON column.

## Setup

The model needs a `permissions` column and the mixin applied using `compose`.

::steps

### Create the migration

If your `users` table does not already have a `permissions` column, generate a migration to add one.

```sh
node ace make:migration add_permissions_to_users
```

### Define the migration

Open the generated migration and add the `permissions` column. This column stores a JSON array of permission keys assigned directly to the user.

```ts [database/migrations/xxxx_add_permissions_to_users.ts]
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    this.schema.alterTable(this.tableName, (table) => {
      table.text('permissions').defaultTo('[]')
    })
  }

  async down() {
    this.schema.alterTable(this.tableName, (table) => {
      table.dropColumn('permissions')
    })
  }
}

```

### Run the migration

```sh
node ace migration:run
```

### Apply the mixin

Add `withPermissions` to your User model alongside `withRoles` if you are using both.

```ts [app/models/user.ts]
import { UserSchema } from '#database/schema'
import { compose } from '@adonisjs/core/helpers'
import { withRoles, withPermissions } from '@adonisplus/permissions'
import Role from '#models/role'

export default class User extends compose(
  UserSchema,
  withPermissions(), // [!code ++]
  withRoles({
    roleModel: () => Role,
    pivotTable: 'user_roles',
  })
) {}

```

::

## Giving permissions

Use `permissions.getKey()` for type-safe permission keys. Duplicates are ignored automatically. Both methods persist the change immediately.

```ts
import { permissions } from '#start/permissions'

await user.givePermission(permissions.getKey('billing.refund'))
await user.givePermissions([
  permissions.getKey('billing.refund'),
  permissions.getKey('product.delete'),
])
```

## Syncing permissions

Use `syncPermissions` to replace all direct permissions with a new list. Any permissions not in the provided list are removed.

```ts
await user.syncPermissions([permissions.getKey('billing.refund')])
```

## Revoking permissions

```ts
await user.revokePermission(permissions.getKey('billing.refund'))
await user.revokePermissions([
  permissions.getKey('billing.refund'),
  permissions.getKey('product.delete'),
])
```

## Combining with roles

When the User model has both `withPermissions` and `withRoles`, calling `getPermissions()` aggregates permissions from all assigned roles and direct assignments into a single deduplicated array.

```ts
// User has "editor" role (with product.create, product.update)
// User also has direct permission: billing.refund

const allPermissions = await user.getPermissions()
// ['billing.refund', 'product.create', 'product.update']
```
