/laravel-permission

name: laravel-permission
description: Use when implementing RBAC, role-based access control, or user authorization with Spatie Laravel Permission.
versions:
  laravel: "13.0"
  spatie-permission: "8.5"
  php: "8.3"
user-invocable: false
references: references/spatie-permission.md, references/middleware.md, references/blade-directives.md, references/teams.md, references/wildcard-permissions.md, references/super-admin.md, references/cache.md, references/direct-permissions.md, references/artisan-commands.md, references/custom-models.md, references/events.md, references/query-scopes.md, references/policies.md, references/api-usage.md, references/testing.md, references/performance.md
related-skills: laravel-auth, laravel-api, laravel-testing

<objective> Covers Spatie Laravel Permission for role-based access control: roles and permissions, route middleware, Blade authorization directives, multi-tenant team scoping, wildcard/hierarchical permissions, super-admin bypass, cache management, direct-vs-role permission inheritance, query scopes, event-based audit logging, Policy integration, Sanctum/Passport API usage, custom models (UUID support), and testing patterns. </objective>

Laravel Permission (Spatie)

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Check existing auth patterns 2. **fuse-ai-pilot:research-expert** - Verify Spatie Permission docs via Context7 3. **mcp__context7__query-docs** - Check Laravel authorization patterns

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

Overview

Spatie Laravel Permission provides complete role-based access control (RBAC) for Laravel applications.

| Component | Purpose | |-----------|---------| | **Role** | Group of permissions (admin, writer) | | **Permission** | Single ability (edit articles) | | **Middleware** | Route protection | | **Blade Directives** | UI authorization | | **Teams** | Multi-tenant scoping | | **Wildcards** | Hierarchical permissions | | **Super Admin** | Bypass all checks | | **Events** | Audit logging (v6.15.0+) | | **Query Scopes** | Filter users by role/permission | | **API Support** | Sanctum/Passport integration | | **Policies** | Resource-based authorization |

---

Critical Rules

1. **Seed roles/permissions** in `DatabaseSeeder` 2. **Cache reset** after changes: `php artisan permission:cache-reset` 3. **Use kebab-case** for naming: `edit-articles` 4. **Never hardcode** role checks in controllers - use middleware 5. **Set team context** early in request for multi-tenant apps 6. **Specify guard for API** - `permission:edit,api` 7. **Clear cache in tests** - Reset in setUp()/beforeEach()

---

Reference Guide

Core Concepts

| Topic | Reference | When to consult | |-------|-----------|-----------------| | **Setup** | [spatie-permission.md](references/spatie-permission.md) | Installation, model setup, core methods | | **Middleware** | [middleware.md](references/middleware.md) | Route protection patterns | | **Blade** | [blade-directives.md](references/blade-directives.md) | UI authorization directives | | **Direct vs Role** | [direct-permissions.md](references/direct-permissions.md) | Permission inheritance |

Advanced Features

| Topic | Reference | When to consult | |-------|-----------|-----------------| | **Teams** | [teams.md](references/teams.md) | Multi-tenant permissions | | **Wildcards** | [wildcard-permissions.md](references/wildcard-permissions.md) | Hierarchical patterns | | **Super Admin** | [super-admin.md](references/super-admin.md) | Bypass all permissions | | **Custom Models** | [custom-models.md](references/custom-models.md) | UUID, extending models |

Integration

| Topic | Reference | When to consult | |-------|-----------|-----------------| | **API Usage** | [api-usage.md](references/api-usage.md) | Sanctum, guards, JSON responses | | **Policies** | [policies.md](references/policies.md) | Laravel Policy integration | | **Query Scopes** | [query-scopes.md](references/query-scopes.md) | `User::role()`, `User::permission()` | | **Events** | [events.md](references/events.md) | Audit logging, notifications |

Operations & Quality

| Topic | Reference | When to consult | |-------|-----------|-----------------| | **Cache** | [cache.md](references/cache.md) | Performance, debugging | | **CLI** | [artisan-commands.md](references/artisan-commands.md) | Artisan commands | | **Testing** | [testing.md](references/testing.md) | Tests, factories, setup | | **Performance** | [performance.md](references/performance.md) | Optimization, N+1, caching |

---

Templates (Code Examples)

Setup & Seeding

| Template | Purpose | |----------|---------| | [UserModel.php.md](references/templates/UserModel.php.md) | User model with HasRoles trait | | [RoleSeeder.php.md](references/templates/RoleSeeder.php.md) | Basic role seeding | | [PermissionSeeder.php.md](references/templates/PermissionSeeder.php.md) | Permission creation seeder | | [WildcardSeeder.php.md](references/templates/WildcardSeeder.php.md) | Hierarchical permissions |

Routes & Middleware

| Template | Purpose | |----------|---------| | [routes-example.md](references/templates/routes-example.md) | Protected routes examples | | [ControllerMiddleware.php.md](references/templates/ControllerMiddleware.php.md) | Middleware in controllers | | [BladeExamples.blade.md](references/templates/BladeExamples.blade.md) | Blade directive examples |

Teams & Multi-Tenant

| Template | Purpose | |----------|---------| | [TeamMiddleware.php.md](references/templates/TeamMiddleware.php.md) | Multi-tenant middleware | | [TeamSeeder.php.md](references/templates/TeamSeeder.php.md) | Team-scoped roles seeder | | [TeamModel.php.md](references/templates/TeamModel.php.md) | Team model with boot |

Super Admin & Cache

| Template | Purpose | |----------|---------| | [SuperAdminSetup.php.md](references