Roles and permissions

Vito uses two overlapping role systems:

System roles (UserRole enum) — stored in the users.role column. Controls access to the Filament admin panel and super-admin features.
Tenant roles (Role enum + Spatie Permission) — scoped to a tenant membership. Controls what actions a staff member can perform within a business.

System roles

Defined in App\Domain\Identity\Enums\UserRole:

Enum value	DB value	Description
`SUPER_ADMIN`	`super_admin`	Full platform access, bypasses all tenant checks
`TENANT_OWNER`	`seller`	Owner of one or more tenants (legacy DB value)
`STAFF`	`staff`	Employee member of a tenant
`CUSTOMER`	`user`	End consumer (legacy DB value)

The super_admin role can also be granted by listing an email in the APP_SUPER_ADMINS environment variable (comma-separated). This takes precedence over the database role column.

// User::isSuperAdmin()
$adminEmail = config('auth.super_admin_email');
if ($adminEmail && strcasecmp($this->email, $adminEmail) === 0) {
    return true;
}
return $this->role->value === UserRole::SUPER_ADMIN->value;

Tenant roles and permissions

Tenant-scoped roles are managed by Spatie Laravel Permission and defined in App\Domain\Access\Enums\Role:

Role	Value	Typical use
`OWNER`	`owner`	Full control of the tenant, all permissions
`ADMIN`	`admin`	Manage catalog, orders, staff, analytics
`MANAGER`	`manager`	Manage catalog, orders, and fulfillment
`OPERATOR`	`operator`	View catalog and orders, fulfill orders
`VIEWER`	`viewer`	Read-only access across most resources

Permission list

Permissions are defined in App\Domain\Access\Enums\Permission and assigned to roles in config/rbac.php:

// config/rbac.php — example for the 'admin' role
Role::ADMIN->value => [
    Permission::TENANT_VIEW->value,
    Permission::TENANT_UPDATE->value,
    Permission::CATALOG_VIEW->value,
    Permission::CATALOG_CREATE->value,
    // ...
    Permission::AI_USE->value,
],

Full permission list

Permission	Value	Description
`TENANT_VIEW`	`tenant.view`	View tenant profile
`TENANT_UPDATE`	`tenant.update`	Update tenant profile
`SETTINGS_VIEW`	`settings.view`	View settings
`SETTINGS_UPDATE`	`settings.update`	Update settings
`BILLING_VIEW`	`billing.view`	View billing information
`BILLING_MANAGE`	`billing.manage`	Manage billing and subscriptions
`CATALOG_VIEW`	`catalog.view`	View products
`CATALOG_CREATE`	`catalog.create`	Create products
`CATALOG_UPDATE`	`catalog.update`	Update products
`CATALOG_DELETE`	`catalog.delete`	Delete products
`CATALOG_PUBLISH`	`catalog.publish`	Publish / unpublish products
`MENU_VIEW`	`menu.view`	View menu sections
`MENU_MANAGE`	`menu.manage`	Manage menu sections
`INVENTORY_VIEW`	`inventory.view`	View stock levels
`INVENTORY_ADJUST`	`inventory.adjust`	Adjust stock quantities
`INVENTORY_TRANSFER`	`inventory.transfer`	Transfer stock between locations
`ORDERS_VIEW`	`orders.view`	View orders
`ORDERS_CREATE`	`orders.create`	Create orders
`ORDERS_MANAGE`	`orders.manage`	Update order metadata
`ORDERS_FULFILL`	`orders.fulfill`	Mark orders as fulfilled
`ORDERS_CANCEL`	`orders.cancel`	Cancel orders
`ORDERS_EXPORT`	`orders.export`	Export orders to file
`PAYMENTS_VIEW`	`payments.view`	View payment records
`PAYMENTS_RECORD`	`payments.record`	Record a payment
`CUSTOMERS_VIEW`	`customers.view`	View customer list
`CUSTOMERS_EXPORT`	`customers.export`	Export customer data
`APPOINTMENTS_VIEW`	`appointments.view`	View appointments
`APPOINTMENTS_MANAGE`	`appointments.manage`	Create and update appointments
`STAFF_VIEW`	`staff.view`	View staff list
`STAFF_MANAGE`	`staff.manage`	Invite and manage staff
`STAFF_ASSIGN_ROLES`	`staff.assign_roles`	Assign roles to staff
`MARKETING_VIEW`	`marketing.view`	View campaigns and leads
`MARKETING_MANAGE`	`marketing.manage`	Create and manage campaigns
`ANALYTICS_VIEW`	`analytics.view`	View analytics dashboards
`ANALYTICS_EXPORT`	`analytics.export`	Export analytics data
`INTEGRATIONS_VIEW`	`integrations.view`	View integrations
`INTEGRATIONS_MANAGE`	`integrations.manage`	Configure integrations
`WEBHOOKS_VIEW`	`webhooks.view`	View webhook configurations
`WEBHOOKS_MANAGE`	`webhooks.manage`	Manage webhook configurations
`AI_USE`	`ai.use`	Access AI generation tools

Role presets

config/rbac.php defines presets for common staff roles tied to a plan capability:

Preset	Base role	Key permissions	Requires capability
`cashier`	`operator`	`orders.view`, `orders.manage`, `payments.record`	`checkout_basic`
`kitchen_staff`	`operator`	`orders.view`, `orders.fulfill`	`kitchen_display`
`service_provider`	`operator`	`appointments.view`, `appointments.manage`	`appointment_booking`
`warehouse_clerk`	`operator`	`inventory.view`, `inventory.adjust`, `inventory.transfer`	`inventory_tracking`

Checking permissions in code

In PHP (Spatie)

// Check a permission
$user->can('orders.view');

// Check a role
$user->hasRole('admin');

// Assign a role to a user
$user->assignRole('manager');

// Give a direct permission
$user->givePermissionTo('catalog.publish');

Checking system role

// Check super admin (email whitelist OR role column)
$user->isSuperAdmin();

// Check tenant ownership (membership or owner column)
$user->isTenantOwner();

In Filament resources

Filament resources respect Laravel’s Gate. Use canAccess or canViewAny methods that delegate to the registered Policy:

// ActivityLogResource — only super_admin and auditor
public static function canAccess(): bool
{
    $user = auth()->user();
    return $user->isSuperAdmin() || $rawRole === 'auditor';
}

Tenant ownership middleware

The tenant.ownership middleware (EnsureTenantOwnership) is applied to all protected tenant API routes:

Route::middleware(['auth:sanctum', 'tenant.ownership', 'throttle:api'])->group(function () {
    Route::prefix('orders')->group(function () { ... });
    Route::prefix('settings')->group(function () { ... });
    Route::prefix('reports')->group(function () { ... });
});

For every route-model-bound parameter, the middleware verifies that the model’s tenant_id belongs to one of the authenticated user’s tenants. On a mismatch:

A TENANT_OWNERSHIP_VIOLATION event is logged to the security log channel.
The request is aborted with 404 (not 403) to avoid disclosing resource existence.

Models covered: Product, Order, Coupon, MenuSection, Lead, Campaign.

Impersonation

Super-admins can impersonate tenant users directly from the Filament admin panel. The original admin session is preserved in impersonator_id and impersonator_name session keys.

Leaving impersonation

GET /impersonate/leave

The ImpersonationController::leave method:

Verifies that an active impersonation session exists (impersonator_id in session).
Logs the impersonation_ended event with the original admin ID, impersonated user ID, IP, and user agent.
Clears the impersonation session keys.
Logs out the impersonated user and restores the original admin session.
Regenerates the session ID to prevent session fixation.

$this->logger->info('impersonation_ended', [
    'original_admin_id'   => $impersonatorId,
    'impersonated_user_id' => $impersonatedUserId,
    'ip_address'          => $request->ip(),
    'user_agent'          => $request->userAgent(),
    'timestamp'           => now()->toIso8601String(),
]);

$request->session()->forget(['impersonator_id', 'impersonator_name', 'password_hash_check']);
$this->auth->logout();
$admin = User::query()->find($impersonatorId);
$this->auth->login($admin);
$request->session()->regenerate();

If the original admin account cannot be found after impersonation ends (e.g., it was deleted), the session is fully invalidated and the browser is redirected to /login. This failure is logged at emergency severity.

Get Started

Architecture

Core Features

Authentication

Admin Panels

Realtime & Notifications

Operations

System roles

Tenant roles and permissions

Permission list

Role presets

Checking permissions in code

In PHP (Spatie)

Checking system role

In Filament resources

Tenant ownership middleware

Impersonation

Leaving impersonation

Build docs developers (and LLMs) love

Get Started

Architecture

Core Features

Authentication

Admin Panels

Realtime & Notifications

Operations

Documentation Index

​System roles

​Tenant roles and permissions

​Permission list

​Role presets

​Checking permissions in code

​In PHP (Spatie)

​Checking system role

​In Filament resources

​Tenant ownership middleware

​Impersonation

​Leaving impersonation

Build docs developers (and LLMs) love

System roles

Tenant roles and permissions

Permission list

Role presets

Checking permissions in code

In PHP (Spatie)

Checking system role

In Filament resources

Tenant ownership middleware

Impersonation

Leaving impersonation