TenantAtlas/specs/065-tenant-rbac-v1/quickstart.md

Quickstart: Tenant RBAC v1

This guide provides a quick overview for developers on how to use the Tenant RBAC v1 system.

Checking Permissions

The core of the RBAC system is a set of defined capabilities. To check if the currently authenticated user has a specific capability, use Laravel's Gate facade.

NEVER check for roles directly. Always check for capabilities.

In PHP (Controllers, Policies, Livewire Components)

use Illuminate\Support\Facades\Gate;

// Check for a specific capability
if (Gate::allows('tenant.members.manage')) {
    // User can manage members
}

// You can also deny access
if (Gate::denies('tenant.settings.manage')) {
    abort(403);
}

In Blade Views

You can use the @can and @cannot directives in your Blade templates to conditionally show UI elements.

@can('tenant.members.manage')
    <button>Add Member</button>
@endcan

@cannot('tenant.danger_zone')
    <p>You are not authorized to access the danger zone.</p>
@endcannot

In Filament Resources

Filament actions and pages can be protected using the can method.

use Filament\Actions\Action;
use Filament\Resources\Pages\ListRecords;

// Protecting an action
Action::make('delete')
    ->requiresConfirmation()
    ->action(fn ($record) => $record->delete())
    ->visible(fn ($record) => Gate::allows('tenant.policies.delete', $record));

// Protecting a page
class ListMembers extends ListRecords
{
    // ...
    public static function canView(): bool
    {
        return Gate::allows('tenant.members.view');
    }
}

Capability Reference

A full list of available capabilities is defined in specs/065-tenant-rbac-v1/contracts/capabilities.md.

Key Principles

1. Capabilities, Not Roles: All authorization checks MUST be against capabilities, not roles (owner, manager, etc.). This decouples the application's logic from the role definitions.
2. Server-Side Enforcement: UI hiding is not security. Always enforce permissions on the server-side (in controllers, actions, or policies) in addition to hiding UI elements.
3. Use Policies for Model-Specific Logic: For authorization logic that depends on a specific model instance, use a Laravel Policy class.