Roles and Permissions Management in Avalúo Vehicular

Avalúo Vehicular uses Spatie Laravel Permission to implement role-based access control (RBAC) throughout the application. Every authenticated user is assigned exactly one role, and fine-grained permissions can be attached to those roles to control access to individual features — such as sharing or deleting appraisals. The RolesController enforces that all role and permission management actions are restricted to users holding the admin role.

Role and permission data is stored in five tables created by the Spatie migration (2026_01_14_103816_create_permission_tables): permissions, roles, model_has_permissions, model_has_roles, and role_has_permissions. Spatie caches this data for performance; the application clears that cache automatically after every create, update, or delete operation by calling PermissionRegistrar::forgetCachedPermissions().

Built-In Roles

`admin`

The administrator role has unrestricted access to the entire application. Admins can:

View, create, update, suspend, and delete all user accounts
Manage roles and permissions
Configure vehicle brand depreciation rates
View the recycle bin for all evaluators and permanently delete records
View and manage all shared appraisals regardless of ownership
Access the panel-prefixed permissions panel

The admin role is protected — the system prevents it from being deleted (destroyRole returns an error if $role->name === 'admin').

`evaluator`

Evaluators are the primary users of the appraisal workflow. They can:

Create, view, edit, and delete their own vehicle registrations and appraisals
Access only their own records in the recycle bin
Share their appraisals with other users (subject to the update_avaluocompartido and delete_avaluocompartido permissions)

Evaluators do not have access to user management, role configuration, or depreciation settings.

Routes

All routes are grouped under the /roles prefix and require the auth and verified middleware. Every action additionally checks Auth::user()->hasRole('admin') before proceeding.

View Roles and Permissions

GET /roles/listado

Returns a paginated list of roles (with their assigned permissions), a paginated list of all permissions, permissions whose names begin with panel, and a full un-paginated list of all permissions. This data is used to populate both the roles panel and the permission assignment UI.

Create a Role

POST /roles/crear

Creates a new role and optionally syncs an initial set of permissions to it in a single operation. Required fields:

Field	Rule
`role`	required, string, `max:255`
`permissions`	required, array of permission IDs that exist in `permissions.id`

Update a Role

POST /roles/actualizar/{id}

Renames a role and replaces its full permission set via syncPermissions. Permissions not included in the new list are automatically detached.

Assign Permissions to a Role

POST /roles/asignarPermisos

Synchronises the complete permission set of an existing role. All previously assigned permissions are replaced by the new list. Required fields:

Field	Rule
`role_id`	required, must exist in `roles.id`
`permissions`	required, array of permission IDs that exist in `permissions.id`

Create a Permission

POST /roles/crearPermiso

Creates a standalone permission record. Permission names must be unique within the permissions table. Required fields:

Field	Rule
`permission`	required, string, unique in `permissions.name`

Update a Permission

POST /roles/actualizarPermiso/{id}

Renames an existing permission. The uniqueness check excludes the permission being updated, so renaming to the same name is a no-op rather than an error.

Delete a Role

DELETE /roles/eliminar/{id}

Permanently removes a role. The admin role cannot be deleted. This operation is restricted to users with the admin role.

Delete a Permission

DELETE /roles/eliminarPermiso/{id}

Permanently removes a permission and detaches it from all roles and users. Restricted to users with the admin role.

Key Permissions

The following permissions are used by the application’s own feature code and should be created during initial setup:

Permission Name	Used By	Effect
`update_avaluocompartido`	`ShareController::update`, `ShareController::renovar`	Allows updating or renewing a shared appraisal link
`delete_avaluocompartido`	`ShareController::destroy`	Allows deleting a shared appraisal link

These permissions are checked directly in controller logic:

// Checking a specific permission
if (! Auth::user()->hasPermissionTo('update_avaluocompartido')) {
    return redirect()->back()->with('error', 'No tienes permiso para actualizar el avalúo compartido');
}

// Checking a role
if (! Auth::user()->hasRole('admin')) {
    return back()->with('error', 'No tienes permiso para acceder a esta página');
}

Setting Up Initial Roles

Create the admin role first and assign it to your initial administrator account before creating any other roles. Once the admin role is in place you can use the UI to manage everything else without touching the database directly.

Create the roles

Navigate to /roles/listado and use the Crear Rol form to add the admin and evaluator roles. Provide a unique name for each.

Create the permissions

Use the Crear Permiso form to add the permissions your application needs. At a minimum, create update_avaluocompartido and delete_avaluocompartido so the appraisal sharing feature works correctly.

Assign permissions to roles

Select each role and use the Asignar Permisos form (or the update route) to attach the relevant permissions. Use POST /roles/asignarPermisos with the role_id and an array of permissions IDs.

Assign roles to users

Navigate to /usuarios/listado and use the role assignment panel to set the correct role for each user account via POST /usuarios/cambiar-rol/{id}.

Operations Reference

Operation	Route	Required Role
View roles and permissions	`GET /roles/listado`	`admin`
Create a role	`POST /roles/crear`	`admin`
Update a role	`POST /roles/actualizar/{id}`	`admin`
Assign permissions to a role	`POST /roles/asignarPermisos`	`admin`
Create a permission	`POST /roles/crearPermiso`	`admin`
Update a permission	`POST /roles/actualizarPermiso/{id}`	`admin`
Delete a role	`DELETE /roles/eliminar/{id}`	`admin`
Delete a permission	`DELETE /roles/eliminarPermiso/{id}`	`admin`

Introducción

Instalación

Configuración

Características

Administración

Roles and Permissions Management in Avalúo Vehicular

Built-In Roles

`admin`

`evaluator`

Routes

View Roles and Permissions

Create a Role

Update a Role

Assign Permissions to a Role

Create a Permission

Update a Permission

Delete a Role

Delete a Permission

Key Permissions

Setting Up Initial Roles

Operations Reference

Build docs developers (and LLMs) love

Introducción

Instalación

Configuración

Características

Administración

Documentation Index

​Built-In Roles

​admin

​evaluator

​Routes

​View Roles and Permissions

​Create a Role

​Update a Role

​Assign Permissions to a Role

​Create a Permission

​Update a Permission

​Delete a Role

​Delete a Permission

​Key Permissions

​Setting Up Initial Roles

​Operations Reference

Build docs developers (and LLMs) love

Built-In Roles

`admin`

`evaluator`

Routes

View Roles and Permissions

Create a Role

Update a Role

Assign Permissions to a Role

Create a Permission

Update a Permission

Delete a Role

Delete a Permission

Key Permissions

Setting Up Initial Roles

Operations Reference