Skip to main content
Permissions are the foundation of the role-permission system. Each permission represents a specific action or capability in your application.

​
Creating Permissions

There are several ways to create permissions in Laravel Permission.
The most common way to create a permission:
use Spatie\Permission\Models\Permission;

Permission::create(['name' => 'edit articles']);
The guard_name is automatically set to your default guard if not specified.

​
Finding Permissions

Retrieve existing permissions using various lookup methods.
1

Find by Name

The most common way to retrieve a permission:
$permission = Permission::findByName('edit articles');

// With specific guard
$permission = Permission::findByName('edit articles', 'api');
Throws PermissionDoesNotExist exception if the permission is not found.
2

Find by ID

Retrieve a permission by its database ID:
$permission = Permission::findById(1);

// With specific guard
$permission = Permission::findById(1, 'api');
3

Find or Create

Safe method that returns existing permission or creates a new one:
// Never throws an exception
$permission = Permission::findOrCreate('edit articles');

​
Permission Properties

Each permission model has the following properties:
PropertyTypeDescription
idint|stringPrimary key
namestringPermission name (e.g., ‘edit articles’)
guard_namestringAuthentication guard (e.g., ‘web’, ‘api’)
created_atCarbonCreation timestamp
updated_atCarbonLast update timestamp

​
Permission Relationships

Permissions have two main relationships:

​
Roles Relationship

A permission can be assigned to multiple roles: 
// Get all roles that have this permission
$permission = Permission::findByName('edit articles');
$roles = $permission->roles; // Collection of Role models

// Count roles with this permission
$roleCount = $permission->roles()->count();

​
Users Relationship

A permission can be assigned directly to users: 
// Get all users with this permission (direct assignment)
$permission = Permission::findByName('edit articles');
$users = $permission->users; // Collection of User models

// This only returns users with DIRECT permission assignment
// It does not include users who have the permission via roles

​
Deleting Permissions

Remove permissions from the database: 
$permission = Permission::findByName('edit articles');
$permission->delete();
When you delete a permission:
  • It’s automatically detached from all roles
  • It’s automatically detached from all users
  • The permission cache is cleared

​
Best Practices

Naming Convention: Use lowercase with spaces or kebab-case for consistency:
  • Good: edit articles, delete-posts, view dashboard
  • Avoid: EditArticles, DELETE_POSTS
Seeders: Create permissions in database seeders for consistent deployment across environments:
// database/seeders/PermissionSeeder.php
public function run()
{
    $permissions = [
        'edit articles',
        'delete articles',
        'publish articles',
        'unpublish articles',
    ];

    foreach ($permissions as $permission) {
        Permission::findOrCreate($permission);
    }
}

​
Guard-Specific Permissions

When using multiple authentication guards, create separate permissions for each: 
// Web guard (for regular users)
Permission::create(['name' => 'edit articles', 'guard_name' => 'web']);

// API guard (for API authentication)
Permission::create(['name' => 'edit articles', 'guard_name' => 'api']);

// Admin guard (for admin panel)
Permission::create(['name' => 'edit articles', 'guard_name' => 'admin']);
Permissions with the same name but different guards are treated as separate permissions.

​
Next Steps

Using Roles

Learn how to create and manage roles

Assigning Permissions

Assign permissions to users and roles

Build docs developers (and LLMs) love

Get started for freeTalk to us