# Defining permissions

This guide covers the `definePermissions` function and the `Permissions` class. You will learn how to:

- Define permissions using the resource/action pattern
- Use prefixes to namespace permissions
- Mark permissions as inactive or create aliases
- Query the permission definitions at runtime

## Overview

Permissions are defined as a flat resource/action map. Each resource (like `product` or `billing`) contains actions (like `create`, `update`, `delete`). The combination produces permission keys in `resource.action` format, for example `product.create` or `billing.refund`.

You define permissions once in a dedicated file and import the resulting `Permissions` instance wherever you need it.

## Basic definition

Use `definePermissions` to create a `Permissions` instance. Each action value controls how the permission is configured:

- `true` uses the resource and action as the description, for example `Product create`.
- A `string` uses that string as the description.
- An `object` provides full control over description, inactive state, and aliases.

```ts [start/permissions.ts]
import { definePermissions } from '@adonisplus/permissions'

export const permissions = definePermissions({
  product: {
    create: true,
    update: 'Update existing products',
    delete: {
      description: 'Delete products permanently',
    },
  },
  billing: {
    refund: 'Issue refunds to customers',
  },
})

export type PermissionKey = ReturnType<typeof permissions.keys>[number]
```

This produces four permission keys: `product.create`, `product.update`, `product.delete`, and `billing.refund`. All keys are type-safe. Your editor will autocomplete them wherever a permission key is expected.

## Using prefixes

Use the `prefix` function to namespace a group of permissions. This is useful when different parts of your application have overlapping resource names.

```ts [start/permissions.ts]
import { definePermissions, prefix } from '@adonisplus/permissions'

export const permissions = definePermissions(
  prefix('admin', {
    product: { create: true, update: true, delete: true },
  }),
  {
    billing: { refund: 'Issue refunds' },
  }
)

export type PermissionKey = ReturnType<typeof permissions.keys>[number]
```

The prefixed keys become `admin:product.create`, `admin:product.update`, and `admin:product.delete`. The colon separates the prefix from the resource, and the dot separates the resource from the action.

You can pass multiple definition objects to `definePermissions`. They are merged together into a single `Permissions` instance.

## Aliases

Aliases let you rename permission keys without breaking existing role assignments. When a user or role has an alias stored in the database, `filterKeys` maps it to the canonical key.

```ts [start/permissions.ts]
import { definePermissions } from '@adonisplus/permissions'

export const permissions = definePermissions({
  product: {
    delete: {
      description: 'Delete products',
      aliases: ['product.remove'],
    },
  },
})

export type PermissionKey = ReturnType<typeof permissions.keys>[number]
```

A role with `product.remove` in the database passes checks for `product.delete` in `Access`, the `authorize` middleware and the Bouncer abilities.

## Inactive permissions

Mark a permission as inactive to remove it from runtime checks without deleting it from the definition. Inactive permissions are excluded from access checks, meaning roles that have the key stored in the database will no longer receive it.

```ts [start/permissions.ts]
import { definePermissions } from '@adonisplus/permissions'

export const permissions = definePermissions({
  product: {
    archive: {
      description: 'Archive products',
      inactive: true,
    },
  },
})

export type PermissionKey = ReturnType<typeof permissions.keys>[number]
```

This is useful when deprecating a permission. The key remains in `.keys()` and `.all()` for reference. `Access`, the `authorize` middleware and Bouncer deny it.

## Reference

The `Permissions` instance lets you inspect the definition at runtime. Admin UIs use it to list the permissions a role can get.

::::field-group

:::field{name="definePermissions" type="(...definitions) => Permissions"}
Creates the `Permissions` instance. When two definitions have the same resource, their actions merge, and a later action replaces an earlier one.
:::

:::field{name="prefix" type="(name: string, definition) => definition"}
Prefixes each resource of the definition with `name:`, for example `admin:product.create`.
:::

:::field{name="all" type="() => Permission[]"}
Returns every permission, with its `key`, `description`, `inactive` and `aliases`.
:::

:::field{name="keys" type="() => PermissionKey[]"}
Returns every key, inactive ones included.
:::

:::field{name="active" type="() => PermissionKey[]"}
Returns the active keys.
:::

:::field{name="getKey" type="(key: PermissionKey) => PermissionKey"}
Returns the key you pass. It exists for type safety. It throws `Unknown permission key: "<key>"` for a key that is not defined.
:::

:::field{name="filterKeys" type="(rawKeys: string[]) => PermissionKey[]"}
Resolves aliases and drops inactive and unknown keys.

```ts
permissions.filterKeys(['product.remove', 'product.archive', 'unknown.key'])
// ['product.delete']
```
:::

:::field{name="createAccess" type="() => Access"}
Returns an empty `Access`. Fill it with `access.use(rawKeys)`.
:::

:::field{name="createAccessFor" type="(entity: ModelWithPermissions) => Promise<Access>"}
Returns an `Access` filled from `entity.getPermissions()`, and keeps it on the entity.
:::

:::field{name="abilities" type="() => Record<PermissionKey, BouncerAbility>"}
Returns one Bouncer ability for each key. An inactive key denies access. See [Bouncer integration](/docs/packages/permissions/bouncer-integration).
:::

::::
