Grav User Management: Roles and Permissions | OpsBlu Docs

Grav User Management: Roles and Permissions

Manage user accounts, groups, and permissions in Grav CMS. Covers the file-based user system, YAML-defined permissions, admin plugin access levels, and...

Grav is a flat-file CMS with no database. User accounts, groups, and permissions are stored as YAML files in the filesystem. The Admin plugin provides a web-based interface for user management, while advanced configuration requires editing YAML files directly.

Permission model overview

Grav's access control is based on:

  • User accounts -- YAML files stored in user/accounts/ (one file per user, e.g., user/accounts/admin.yaml)
  • Groups -- Defined in user/config/groups.yaml. Each group has a set of permissions. Users can belong to multiple groups.
  • Permissions -- Dot-notation strings (e.g., admin.login, admin.pages, admin.configuration) that grant access to specific admin features
  • Access rules -- Each user or group has an access property listing permissions with boolean values

Permissions are additive across group memberships and user-level overrides.

Key permissions

Grav uses a hierarchical dot-notation permission system. The main permissions are:

  • site.login -- Can log into the frontend (for restricted-access sites)
  • admin.login -- Can log into the Admin panel at /admin
  • admin.super -- Super admin with full access to everything. Overrides all other permission checks.
  • admin.pages -- Can manage pages (create, edit, delete, reorder) in the Admin panel
  • admin.configuration -- Can access the Configuration tab (system, site, media, and security settings)
  • admin.plugins -- Can install, configure, enable, and disable plugins
  • admin.themes -- Can install, configure, and switch themes
  • admin.users -- Can manage user accounts (add, edit, delete users)
  • admin.statistics -- Can view the dashboard statistics panel
  • admin.cache -- Can clear the Grav cache from the admin panel
  • admin.maintenance -- Can run maintenance tasks (Grav updates, dependency checks)
  • admin.tools -- Can access admin tools (direct install, backups)

Wildcard access is supported: admin.* grants all admin permissions (equivalent to admin.super in practice, though admin.super is the canonical way).

User account files

Each user is defined in a YAML file at user/accounts/{username}.yaml:

email: editor@example.com
fullname: Jane Editor
title: Content Editor
state: enabled
access:
  admin:
    login: true
    pages: true
    statistics: true
  site:
    login: true

The state field controls whether the account is active (enabled) or disabled. The access block defines the user's direct permissions.

Groups

Groups are defined in user/config/groups.yaml:

editors:
  readableName: Content Editors
  description: Can manage pages and view statistics
  access:
    admin:
      login: true
      pages: true
      statistics: true
    site:
      login: true

admins:
  readableName: Administrators
  access:
    admin:
      super: true
    site:
      login: true

Users are assigned to groups via their account file:

groups:
  - editors

Managing users via the Admin panel

If the Admin plugin is installed (which it is by default), manage users at /admin:

Adding a user:

  1. Go to Admin > User Accounts (accessible to users with admin.users permission)
  2. Click Add (the plus icon)
  3. Enter username, password, email, full name, and title
  4. Set the account state to Enabled
  5. Assign groups and/or set individual permissions under the Permissions tab
  6. Save

Editing a user:

  1. Go to Admin > User Accounts
  2. Click the user
  3. Modify groups, permissions, or account details
  4. Save

Disabling/removing a user:

  1. Set the state to Disabled to block login while preserving the account
  2. Or delete the account file from user/accounts/ (there is no delete button in older Admin versions)

CLI user management

Grav's CLI tool can manage users without the Admin panel:

# Create a new user interactively
bin/grav newuser

# Create a user non-interactively
bin/plugin login new-user --user=editor --password=secret --email=editor@example.com --permissions=b --fullname="Jane Editor" --title="Editor" --state=enabled

The --permissions flag sets access level: a for admin, s for site, b for both.

API access

Grav does not have a built-in REST API. For headless or API-based access:

  • The API plugin (community) adds RESTful endpoints for page data
  • Authentication for API requests uses the same user accounts and permissions
  • For custom integrations, Grav plugins can define routes and authenticate against the user system
  • There are no API tokens or OAuth support in core Grav -- API authentication is session or Basic Auth based

Analytics and tracking permissions

  • Tracking code injection -- Add Google Analytics, GTM, or other tracking scripts by editing the theme's base.html.twig template (in user/themes/{theme}/templates/). Requires filesystem access or admin access to edit theme files.
  • Custom CSS/JS -- Some themes support custom header/footer code in their settings under Admin > Themes > [Theme] > Custom. Requires admin.themes permission.
  • Admin panel analytics -- The Admin dashboard shows a statistics widget (page views, visitor counts) if the admin.statistics permission is granted. This uses built-in tracking that records page views to a YAML data file.
  • Plugin-based analytics -- Analytics plugins (Google Analytics, Matomo, etc.) are configured under Admin > Plugins > [Plugin Name]. Requires admin.plugins permission to install and admin.configuration to configure.

A user with only admin.pages cannot install analytics plugins or modify theme templates. Analytics setup requires either admin.plugins + admin.themes or direct filesystem access.

Security considerations

  • Grav stores passwords using bcrypt hashing in the YAML account files
  • The admin panel is accessible at /admin by default (not customizable without server-level URL rewriting)
  • There is no built-in SSO, LDAP, or SCIM support
  • Two-factor authentication is available via the 2FA plugin
  • Rate limiting for login attempts is configurable in the Login plugin settings
  • Since user data is in YAML files, backup the user/accounts/ directory and user/config/groups.yaml as part of site backups
  • There is no built-in admin audit log -- page changes are tracked via Git if the Git Sync plugin is installed

Sub-pages in this section

  • Roles and Permissions -- Complete permission reference, group configuration patterns, and recommended access templates
  • Adding and Removing Users -- Admin panel and CLI user creation, group assignment, and account lifecycle management
Back to top