Skip to content

Permissions

User permissions help you to restrict access and capabilities for specific user roles – in the Panel as well as when using Kirby's PHP API or REST API.

Defining permissions

Permissions in Kirby can be defined in two places:

  1. In a user blueprint for each role
  2. In the page, file or the site blueprint for more detailed rules

User blueprint

Each role can have its own blueprint with custom fields for users with that role and optional user permissions. User blueprints are stored in /site/blueprints/users and get the name of each role (i.e /site/blueprints/users/editor.yml).

Permissions are only valid for custom roles. The admin role does not obey to those settings and can always do anything.

Here is an overview of all available permissions:

/site/blueprints/users/editor.yml
title: Editor
permissions:
  access:
    panel: true
    site: true
    settings: false
  files:
    create: true
    changeName: true
    delete: true
    replace: true
    update: false
  site:
    update: false
  pages:
    create: true
    changeTemplate: true
    changeTitle: true
    changeSlug: true
    delete: false
    hide: true
    sort: true
    update: true
  user:
    create: false
    changeName: false
    changeEmail: false
    changePassword: false
    changeRole: false
    delete: false
    update: false
  users:
    create: true,
    changeEmail: false,
    changeLanguage: true,
    changeName: false,
    changePassword: false,
    changeRole: false,
    delete: false,
    update: false

You don't have to set all permissions for each role. Each permission is set to true by default, if not specified otherwise.

You can also enable or disable entire permission sections by passing true or false instead of an array of definitions for each action. A more simple permission setup for an editor, who should not be allowed to edit other users, could look like this:

/site/blueprints/users/editor.yml
title: Editor
permissions:
  site:
    update: false
  pages:
    delete: false
  users: false
  user:
    changeRole: false

This would prevent the editor from editing other users (users: false), from changing their own role, from deleting pages and from updating the site settings.

The * wildcard

For permission types with many actions with the same setting, you can use the * wildcard as first argument. Afterwards you can still override specific actions, for example to whitelist actions:

user:
  *: false
  changeName: true

Visitors

Frontend users can also be managed through the Panel, but you most likely don't want them to be able to access the Panel at all. In order to achieve this, set Panel access to false.

title: Visitor
permissions:
  access:
    panel: false

If you use any of Kirby's PHP APIs in the frontend to modify pages, files, the site or users, you should set the permissions like above to control what a visitor can do in your frontend. You can also have multiple frontend user roles without access to the Panel but with different access rights to the PHP APIs. Our REST API follows the same rules.

Getting more specific

You can keep all permissions in the role files, but you can also overwrite them individually per page, file, user or the site in the corresponding blueprints. Those specific permission settings will always override the role settings.

Page options

/site/blueprints/pages/project.yml
title: Project

options:
  changeTemplate: false
  changeTitle: false
  update: true
  delete: false

Even more control with hooks

If the blueprint-based permission settings are too limiting for your project, you can get more flexibility by creating your own permission checks with before hooks for various actions.

/site/config/config.php
return [
  'hooks' => [
    'page.delete:before' => function (Page $page) {
      if ($this->user()->email() !== 'overlord@ourcompany.com') {
        throw new Exception('Only our overlord and savior can delete pages');
      }
    }
  ]
];

Of course this can be more complex and sophisticated than that, but it's a good first start.

Authenticate or impersonate

To obtain the required permissions for certain actions, you can authenticate as a user by logging in. If you want to run actions programmatically without logging in, you can also impersonate a user.

Authentication

Users can log in through the Panel login page or a custom login form. To learn more about how to log in a user programmatically, read the reference for $user->login().

Impersonate

One way to go without authentication is to impersonate an existing user or the special kirby super user, which has full permissions:

<?php

$kirby = kirby();
$kirby->impersonate('kirby');

page('notes/a-great-article')->update([
  'author'  => 'Homer Simpson'
]);

The impersonation will only last for the current request.