Defining permissions
On this page
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
Section titled "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
Section titled "Basic definition"Use definePermissions to create a Permissions instance. Each action value controls how the permission is configured:
trueuses the resource and action as the description, for exampleProduct create.- A
stringuses that string as the description. - An
objectprovides full control over description, inactive state, and aliases.
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
Section titled "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.
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
Section titled "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.
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
Section titled "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.
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
Section titled "Reference"The Permissions instance lets you inspect the definition at runtime. Admin UIs use it to list the permissions a role can get.
definePermissions(...definitions) => PermissionsPermissions instance. When two definitions have the same resource, their actions merge, and a later action replaces an earlier one.prefix(name: string, definition) => definitionname:, for example admin:product.create.all() => Permission[]key, description, inactive and aliases.keys() => PermissionKey[]active() => PermissionKey[]getKey(key: PermissionKey) => PermissionKeyUnknown 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() => AccessAccess. Fill it with access.use(rawKeys).createAccessFor(entity: ModelWithPermissions) => Promise<Access>Access filled from entity.getPermissions(), and keeps it on the entity.abilities() => Record<PermissionKey, BouncerAbility>