Direct permissions
Most of the time permissions should come from roles. Sometimes a single user needs one extra permission, though, and creating a role just for that is overkill. For those cases you can give permissions straight to a subject.
TIP
Prefer roles where you can. Direct permissions are harder to audit because they are spread across individual users. See Roles vs permissions.
Giving and revoking
The permission must exist first:
await rbac.createPermission('publish articles')
const user = rbac.for({ type: 'user', id: 1 })
await user.givePermissionTo('publish articles')
await user.revokePermissionTo('publish articles')Several at once, as arguments or an array:
await user.givePermissionTo('edit articles', 'publish articles')
await user.givePermissionTo(['edit articles', 'publish articles'])Giving a permission the subject already has does nothing. Revoking one it doesn't have does nothing either. Using a name that doesn't exist throws PermissionDoesNotExist.
For a limited time
A direct permission can end on its own (1.2, needs an adapter created with { expiry: true }). Pass a last { expiresAt }; from that moment on, checks treat the permission as gone:
await user.givePermissionTo('customers.impersonate', { expiresAt: new Date(Date.now() + 2 * 3_600_000) })
await user.getDirectPermissionAssignments() // [{ permission: { name: 'customers.impersonate', ... }, expiresAt: ... }]Giving it again sets a new end (the latest call wins); without expiresAt it becomes permanent. Permissions the subject has through a role are not affected. See Temporary access.
Syncing
syncPermissions() replaces all of the subject's direct permissions with the given list. Permissions it gets through roles are not touched.
await user.syncPermissions('edit articles', 'publish articles')
await user.syncPermissions() // remove all direct permissionsrevokeAll() removes the direct permissions and the roles. See Roles and Teams.
Checking
There are three kinds of checks:
// Authorization check: honors `before` and superAdminRoles, never throws
await user.can('publish articles')
// Data check, direct permissions or via roles; throws if the permission doesn't exist
await user.hasPermissionTo('publish articles')
// Data check, direct permissions only; throws if the permission doesn't exist
await user.hasDirectPermission('publish articles')For several permissions at once:
await user.canAny('edit articles', 'publish articles')
await user.canAll(['edit articles', 'publish articles'])
await user.hasAnyPermission('edit articles', 'publish articles')
await user.hasAllPermissions('edit articles', 'publish articles')hasAnyPermission() and hasAllPermissions() are data checks like hasPermissionTo(), but they never throw: an unknown permission simply counts as missing.
Reading permissions
await user.getDirectPermissions() // Permission[] given directly
await user.getPermissionsViaRoles() // Permission[] inherited from roles
await user.getAllPermissions() // both, without duplicates
await user.getPermissionNames() // both, as names: ['edit articles', ...]Scope
Direct permissions are stored per guard and, when teams are enabled, per team:
await rbac.for(user, { team: 42 }).givePermissionTo('publish articles')
await rbac.for(user, { team: 42 }).can('publish articles') // true
await rbac.for(user, { team: 7 }).can('publish articles') // false