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.
Permissions
Section titled “Permissions”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.
The roles an app starts with
Section titled “The roles an app starts with”| 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.
The people an app starts with
Section titled “The people an app starts with”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:
nevela new my-app --no-sample-usersTo add them to an app that doesn’t have them:
nevela user --sampleManaging users
Section titled “Managing users”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:
nevela user --name="Ada Okafor" --email=ada@example.com --role=EDITORManaging roles
Section titled “Managing roles”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.
EDITORhas 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.
The trash
Section titled “The trash”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.
Three rules that can’t be switched off
Section titled “Three rules that can’t be switched off”Being allowed to manage users or roles is never a way to get more than you were given.
- 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.
- You change only accounts that may do no more than you. Someone with
users.editand 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. - 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.
In your Laravel code
Section titled “In your Laravel code”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.
Which records each person sees
Section titled “Which records each person sees”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:
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:
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.
Permissions of your own
Section titled “Permissions of your own”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');Granting by pattern
Section titled “Granting by pattern”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.
What the dashboard does with them
Section titled “What the dashboard does with them”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"] },};People who sign up
Section titled “People who sign up”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.
Upgrading an app from before 0.5.0
Section titled “Upgrading an app from before 0.5.0”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
ADMINwhen 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.
Over the API
Section titled “Over the API”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.