Users, roles, and permissions

Who can use this: Solavel staff. Most pages need Admin; the role and permission editors need Super Admin. URL / Route: /admin/admins/*, /admin/permissions/* (Super Admin), /admin/roles/* (Super Admin), plus /admin/client-users/* Plan / feature gate: Always on for staff

Purpose

This page documents the back-office tools for managing Solavel staff accounts, role definitions, and the permission catalog. It also covers the staff-side controls for client user accounts (reset password, deactivate, etc.).

How the role system works

The central app uses the Spatie permission package on the users table, with five seeded roles:

super-admin — every permission.
admin — staff role; permissions assigned per-user.
client_owner — full client-side access (24 permissions).
client_manager — operational client access (16 permissions).
client_member — view-only (5 permissions).

There are 50 permissions split across two halves:

Admin-side (24) — create-admin, edit-admin, view-admin, delete-admin, plus CRUD on projects, clients, plans, project plans, and client subscriptions.
Client-side (26) — organization, team-member, project, role-assignment, and subscription operations such as manage-organization-projects, assign-roles, manage-subscriptions, view-reports, export-data.

The full list is seeded inline by database/seeders/DatabaseSeeder.php. It is the source of truth — if you add a new permission key to a @can directive in a Blade file, it must also be added to the seeder, otherwise the check always returns false.

Note: there is a second, parallel concept stored on user_organizations.role. The strings look the same (client_owner, etc.) but the column is written by SuperAdminProvisioningSeeder directly, not via Spatie. End users do not see this column; it is mostly used by the multitenancy bootstrap to remember which user owns which org. Treat the Spatie role on the user as authoritative for "what can this user do".

Step by step

Admin accounts

Open /admin/admins (admin.admins.index). You see the list of staff accounts.
Click Create admin (/admin/admins/create, route admin.admins.create). Enter their email and name.
The new admin receives a first-time password setup link by email.
To edit an admin, open /admin/admins/{admin}/edit (admin.admins.edit). You can change their name, email, and role assignments.
To remove an admin, use DELETE /admin/admins/{admin} (admin.admins.destroy).

The Promote to Super Admin action lives on admin.admins.edit and is gated by Super Admin only — Admins cannot promote themselves or others.

Roles (Super Admin only)

Open /admin/roles (admin.roles.index). You see all five seeded roles plus any custom ones added later.
Click a role to view it (admin.roles.show) or edit (admin.roles.edit). The form lists every permission with a checkbox; tick the ones the role should hold.
Save (admin.roles.update). Existing users with that role pick up the new permissions on their next request.
Add a brand-new role with admin.roles.create / admin.roles.store. Remove one with admin.roles.destroy.

Risk: deleting a built-in role (client_owner, client_manager, client_member) will break the seeded user-organization rows that reference it by name. Avoid deleting the seeded roles. Re-seed if you do.

Permissions (Super Admin only)

Open /admin/permissions (admin.permissions.index). You see all 50 permissions.
Click a permission to view (admin.permissions.show) or edit (admin.permissions.edit). The edit form lets you change the display name and description; the name field (which @can('...') checks against) is treated as read-only because changing it would silently break Blade gates across the codebase.
Add a permission with admin.permissions.create / admin.permissions.store. After adding, assign it to one or more roles via the roles editor.
Remove with admin.permissions.destroy — only safe for permissions you have just added that are not referenced anywhere.

Client users

Operations on accounts that belong to clients (Organization Owners, Managers, Members) are at:

admin.client-users.index (/admin/client-users) — searchable list of every client user.
admin.client-users.edit (/admin/client-users/{user}/edit) — change name, email, role assignment within the client.
admin.client-users.update — save.
admin.client-users.reset-password (POST /admin/client-users/{user}/reset-password) — emails them a fresh setup link.
admin.client-users.set-status (POST /admin/client-users/{user}/status) — toggle active / inactive.

These tools are how support staff help a customer who has lost access or needs their role changed.

Send Email (Super Admin only)

/admin/emails/create (admin.emails.create) is a compose page. Pick a recipient list (one user, all users in a client, all admins, etc.), write a subject and body, send. The send POST is at admin.emails.send. Use sparingly — every send appears in System event logs.

Permissions / restrictions

/admin/admins/*: Admin (read) and Super Admin (write). The route group is wrapped in EnsureAdmin plus LoadMyWorkspace.
/admin/permissions/*: Super Admin only (EnsureSuperAdmin).
/admin/roles/*: Super Admin only.
/admin/client-users/*: Admin or Super Admin.
/admin/emails/*: Super Admin only.

Inside @can('...') checks in Blade, the user must hold the named permission via one of their roles. Permissions assigned outside of roles (direct user-permission grants) are supported by Spatie but the seeder does not use them — every permission in production is granted via a role.

Common problems

"This action requires super admin privileges." — You opened a Super Admin only page (roles, permissions, projects, send email). Ask a Super Admin.
A button you expected is missing from a page — your role does not include the permission gating that button. Compare against the user roles reference.
A new permission you added is not respected — re-run php artisan permission:cache-reset (Spatie caches permissions for performance), then sign out and sign back in.