Permissions in Kirby can be defined in two places:
- In a user blueprint for each role
- In the page, file or the site blueprint for more detailed rules
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
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:
user permission only applies to the user itself, while the
users permissions sets these permissions for all users.
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
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:
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.
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:
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
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.
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.
You can control each option for pages, files and users in blueprints with fine-grained permissions based on user role:
You can also use a wildcard to change the default for all roles and then assign exceptions to individual roles:
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.
Of course this can be more complex and sophisticated than that, but it's a good first start.
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.
One way to go without authentication is to impersonate an existing user or the special
kirby super user, which has full permissions:
The impersonation will be active for all code that runs in the current request after the call to
$kirby->impersonate(). If you want to limit the impact to a single operation, call the method with a callback (see below).
Impersonate with callback
If you only want a single operation to run with different privileges, use a callback:
The impersonation automatically gets reset to the previous value after the callback returns.
Disable all permissions
It is also possible to disable all permissions, even if a user is currently logged in. This is useful for operations where you want to ensure that no changes are made to the site (read-only access):