Skip to content
Nevela 0.33.1: New: customers get a shop in the mobile app, each sees only their own orders, and an administrator manages people and roles from the phone. Build it in the new drinks-app tutorial.A drinks app on the phone

Users, roles and permissions

Every app has a Users screen and a Roles screen. A role is a set of permissions, a person holds one or more roles, and Laravel checks the permission on every request. If you have used Grit, this is the same model, with the same names.

A permission is feature.action.

Part What it is
feature A resource’s table (products), one of the built-in ones (users, roles), or one you add
action create, view, edit or delete, or one of the resource’s own actions

So a Product resource brings products.create, products.view, products.edit and products.delete. Nothing has to be registered: a resource’s permissions exist as soon as the resource does.

A resource with an accept action also brings applications.accept. It is on the Roles screen under the resource, on a line of its own beneath the four.

Role What it allows
ADMIN Everything, including whatever is added later.
EDITOR Every action on every resource, and seeing who the users are. It manages neither users nor roles.
USER Nothing beyond the person’s own account.

These three are built in: you can change what EDITOR and USER allow and their descriptions, and you can’t rename or delete them. ADMIN always allows everything. Make as many roles of your own as you like on the Roles screen.

Someone with several roles may do everything any of them allows.

A new app has an administrator and ten sample users, all in your local database only:

admin@example.com ADMIN
amara.okafor@example.com, daniel.kim@example.com EDITOR
seven more, such as sofia.martinez@example.com USER
noah.williams@example.com USER, switched off

They all sign in with the password password. Sign in as one of each to see what a role changes: an editor has the resources and a read-only list of users, a user has only their own account, and the switched-off account is turned away.

They are made by the installer, never by a migration, so they don’t follow the app to a server, and nevela user --sample refuses to make them in production. Delete them before real use. To create an app without them:

Terminal window
nevela new my-app --no-sample-users

To add them to an app that doesn’t have them:

Terminal window
nevela user --sample

Users in the sidebar, for anyone whose roles include users.view.

  • Add someone with a name, an email, a password and their roles. They can sign in straight away.
  • Change their roles, their name, their email, or set a new password. A new password signs them out everywhere and they are told by email.
  • Switch an account off. It is kept, signed out of every device, and can’t sign in until it is switched on again.
  • Sign someone out everywhere without changing anything else.
  • Delete an account. It is closed and kept under Deleted accounts, where it can be restored as it was or removed for good, and its email can’t sign up again.

From the command line, nevela user still creates an account. The first one in an app is its ADMIN. After that it asks which role, or takes one:

Terminal window
nevela user --name="Ada Okafor" --email=ada@example.com --role=EDITOR

Roles in the sidebar, for anyone whose roles include roles.view. A role’s page is a grid of every permission there is: a row for each thing and a column for each action.

Two switches save ticking boxes:

  • Everything here, and whatever is added later, on a section. A role with this on the Resources section covers a resource you generate next month without being edited. EDITOR has it.
  • The All box at the end of a row, for every action on one thing.

A change to a role applies from each person’s next request. Nobody has to sign in again.

A role that people hold can’t be deleted: give them another first.

Deleting needs products.delete, and so does everything about a deleted product: seeing it in the trash, restoring it and removing it for good. To make one of those stricter, change restore or forceDelete in the resource’s policy.

Being allowed to manage users or roles is never a way to get more than you were given.

  1. You hand out only what you hold. You can give someone a role, or put a permission in a role, only if your own roles already allow everything it does.
  2. You change only accounts that may do no more than you. Someone with users.edit and nothing else can’t set an editor’s password, change their email, switch them off or delete them, because signing in as that editor would give them the records. Only an administrator changes an administrator’s account.
  3. The last administrator stays. The only remaining administrator can’t be deleted, switched off, or given a lesser role, by anyone. And you can’t switch off or delete your own account.

Laravel enforces these. The dashboard disables what would be refused, and the API refuses it whatever a client sends.

A generated policy asks for the matching permission:

public function update(User $user, Product $product): bool
{
return $user->can('products.edit');
}

The policy file is yours. Add conditions of your own beside the permission:

public function update(User $user, Product $product): bool
{
return $user->can('products.edit') && $product->user_id === $user->id;
}

A rule like that decides one record at a time. For which records someone sees at all, see the next section.

Anything shaped like a permission works wherever Laravel checks an ability: $user->can('products.view'), Gate::authorize('users.edit'), @can('products.delete'), and ->middleware('can:reports.view') on a route.

Where records belong to whoever made them, such as a customer’s orders, say so in the descriptor and Nevela writes this for you:

{ "name": "Order", "owner": "email", "fields": { "email": { "kind": "string", "format": "email" } } }

owner names a string field that holds the owner’s email. Anyone who may edit the resource (orders.edit) sees every record; everyone else sees only the ones whose email is theirs, in the list, the counts, a record’s page, the trash and the bell, and a record they make is made theirs whatever the request said for it. Staff keep what they send, so an order taken by phone can be put under the customer’s email, and one they make without an email is their own. The owner field may be left out of a request, since Laravel fills it. nevela resource Order --fields="…, email:email" --owner=email sets it when the resource is made. nevela:generate adds the Owned trait and its owner() method to the model.

For anything else, a model decides itself. A permission says whether someone may see courses at all. Which courses is the model’s to say, in a visibleTo scope, outside the generated block:

app/Models/Course.php
public function scopeVisibleTo(Builder $query, User $user): void
{
// A teacher sees their own courses. Anyone else who may see courses sees them all.
if (Teacher::where('email', $user->email)->exists()) {
$query->whereHas('teacher', fn (Builder $teacher) => $teacher->where('email', $user->email));
}
}

Nevela asks it wherever records reach someone signed in:

The list Only what it lets through, and so the cards above it, the charts, the export and the pickers of a relation that points here.
One record Its page, changing it, deleting it, its actions and its private files. One it keeps from someone answers 404, as for a record that was never there, not “not allowed”, which would say it exists.
A relation Points only at a record the person saving may see: a teacher can’t move an enrolment into another teacher’s course by sending its id. It is refused as an id that doesn’t exist is.
The trash What it holds of the resource, and what can be restored or removed from it.
The bell Tells each person of the records they may see, and counts those: “Ada created 3 enrolments” is the three in your courses.

A scope can lean on another’s. Enrolments are seen through their course, and whereHas uses the course’s own scope, so this is all it takes:

app/Models/Enrolment.php
public function scopeVisibleTo(Builder $query, User $user): void
{
$query->whereHas('course', fn (Builder $course) => $course->visibleTo($user));
}

It is for someone signed in. A seeder, the scheduler, your own code with nobody signed in and the public site are not narrowed by it; the public site has publicQuery for that.

Two things it doesn’t narrow. The activity log shows every change to a resource to those who have it, so give activity.view only to people who may see everything. And a list action (one on the whole list rather than on chosen records) gets no records from Nevela: it reads what it needs, so ask visibleTo there yourself.

Add them in config/nevela.php. They appear on the Roles screen under App:

'permissions' => [
'reports' => ['name' => 'Reports', 'actions' => ['view']],
],
Route::get('reports', ReportController::class)->middleware('can:reports.view');

A role’s grants can be patterns. The Roles screen writes the first two for you; all of them work through the API.

Grant Covers
* Everything
@resources.* Creating, viewing, editing and deleting every resource, including ones added later
@resources.view Viewing every resource
products.* Creating, viewing, editing and deleting products
*.view Viewing everything, users and roles included

After the dot, * means create, view, edit and delete. A resource’s own action is not one of those: it is covered by its own name (applications.accept) or by * alone, so a role with everything for the records has not been given the button that sends a letter.

The dashboard hides what the signed-in person can’t use: a resource they can’t view isn’t in the sidebar, and the buttons for adding, editing and deleting appear only with the matching permission. Opening a page by its address without the permission sends them back to the dashboard with a note saying why.

This is only for showing and hiding. Laravel decides every request again for itself.

policies/index.ts is still there for hiding more by role name. It can hide, and never show:

export const policies: Record<string, Policy> = {
Product: { read: ["ADMIN", "EDITOR"], delete: ["ADMIN"] },
};

With sign-up open, a new account gets the USER role, which allows nothing beyond their own account. To start them with another, set auth.default_role in config/nevela.php to its name.

Until 0.5.0 every signed-in user could do everything. Upgrading keeps it that way until you decide otherwise:

  • Every existing user becomes an ADMIN when the migration runs (nevela migrate). Nobody loses access. Give people narrower roles from the Users screen when you are ready.
  • Your policies are not touched. They are your files, and they still say return true. To put a resource under permissions, change its policy to ask for them, as in the example above. Until you do, the dashboard hides that resource from people without the permission, and the API still allows it to any signed-in user.

Between upgrading and running the migration, everyone can still do everything, and the Users and Roles screens say the migration is needed.

GET /api/auth/me The signed-in user, with roles, permissions (patterns resolved) and isAdmin
GET /api/_nevela/users List: q, role, status, page, perPage
POST /api/_nevela/users Create: name, email, password, roles (ids), active
PATCH /api/_nevela/users/{id} Any of the same fields
DELETE /api/_nevela/users/{id} Delete: the account is closed and kept. See Deleted accounts for restoring and removing.
DELETE /api/_nevela/users/{id}/sessions Sign them out everywhere
GET /api/_nevela/roles Every role, with what its grants come to and how many people hold it
POST /api/_nevela/roles Create: name, description, grants
PATCH /api/_nevela/roles/{id} Any of the same fields
DELETE /api/_nevela/roles/{id} Delete, when nobody holds it
GET /api/_nevela/permissions Every permission there is, in the sections the Roles screen shows

A refusal says why, with a code: BEYOND_YOUR_OWN, ABOVE_YOUR_OWN, ADMIN_ONLY, LAST_ADMIN, SELF, BUILT_IN or IN_USE.