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

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.

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

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

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

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.

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.

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.

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

definePermissions(...definitions) => Permissions
Creates the Permissions instance. When two definitions have the same resource, their actions merge, and a later action replaces an earlier one.
prefix(name: string, definition) => definition
Prefixes each resource of the definition with name:, for example admin:product.create.
all() => Permission[]
Returns every permission, with its key, description, inactive and aliases.
keys() => PermissionKey[]
Returns every key, inactive ones included.
active() => PermissionKey[]
Returns the active keys.
getKey(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.
filterKeys(rawKeys: string[]) => PermissionKey[]

Resolves aliases and drops inactive and unknown keys.

permissions.filterKeys(['product.remove', 'product.archive', 'unknown.key'])
// ['product.delete']
createAccess() => Access
Returns an empty Access. Fill it with access.use(rawKeys).
createAccessFor(entity: ModelWithPermissions) => Promise<Access>
Returns an Access filled from entity.getPermissions(), and keeps it on the entity.
abilities() => Record<PermissionKey, BouncerAbility>
Returns one Bouncer ability for each key. An inactive key denies access. See Bouncer integration.