User Management

Users in Craft represent humans in the system. These may be control panel users, member accounts, or records that represent people in general. Users implicitly have the ability to create passwords and log in, but must be granted permissions or added to groups to access the control panel or manage content.

The first user account is created during installation. If you stick with the Solo edition, this is the only account you will be able to create. If you need more (or you want to support public registration) you can upgrade to Pro, which offers additional user accounts.

# Statuses

Users may exist in the system in a number of states. A user is typically created in a Pending state (ready to be activated via an activation link), whether via public registration or by another user. Changes to a user’s status can happen implicitly (via activation, failed login attempts, etc.) or explicitly (suspension by a moderator), and sometimes those actions use

An Active user is able perform any task their permissions allow. Users are put in this state following account activation (either via an activation link or action taken by another user). However, an active account does not necessarily have a password—but once one is set (or the current password is reset), they would be able to log in normally.
A user is typically created in Pending state. The only difference between a Pending and Active user is that they have never activated their account with an activation link, or had a user with the Moderate users permission activate it for them.
Suspended users have been manually locked out of the system by an user with the Moderate Users permission. They will be unable to log in or reset their password.
Users that have been explicitly deactivated are marked as Inactive. An inactive user cannot log in, reset their password, or reactivate their account.

# Special States


Craft has a special distinction for users who are able to log in or could become able to log in under their own power. Any user that is either Active or Pending is considered Credentialed.


When a user makes too many unsuccessful login attempts (according to the maxInvalidLogins and invalidLoginWindowDuration settings), their account will be Locked. Another user with the Moderate users permission can manually unlock a user in this state at any time, or the user can wait until the cooldownDuration elapses and try again.

User locking is an automatic abuse-prevention behavior, not a moderation tool. If you need to prevent someone from accessing the site or control panel, suspend or deactivate the user.


Like other elements, users can be soft-deleted. A trashed user cannot log in or restore themselves, and the user may be garbage-collected after remaining trashed for the configured softDeleteDuration.

# Admin Accounts

Admin accounts are special accounts that can do everything within Craft, including some things that don’t have explicit permissions:

  • Everything within the Settings section
  • Make other users Admins Pro
  • Administrate other Admins Pro

The user account you create during installation is an admin by default.

Considering how much damage an admin can do, we strongly advise caution when creating new admin accounts; only create them for those you trust and who know what they’re doing.

# User Groups

If you have Craft Pro, you can create User Groups to help organize your site’s user accounts, as well as batch-set permissions on them.

To create a new User Group, go to SettingsUsers and press + New user group. You can give your group a Name and Handle, plus any Permissions you want every user within the group to have.

After you create your groups, you can assign users to groups by going into their account settings and choosing the Permissions tab. Permissions granted by groups are additive, so a user in multiple groups receives the combined permissions of those groups (as well has any permissions granted explicitly to the user). Removing a user from a group does not revoke permissions that are granted by another group they are a member of!

# Permissions

Craft Pro allows you to set permissions on users and groups, such as the ability to access the control panel, edit content within certain sections, etc. You can apply these permissions directly to user accounts as well as to user groups. Permissions applied to a user group are inherited by all users belonging to it.

Make sure you trust users with access to settings that accept Twig code, like the Settings section and the System Messages utility. It’s possible to do malicious things in Craft via Twig, which is intended primarily for trusted admins and developers.

The permissions Craft comes with are:

Permission Handle
Access the site when the system is off accessSiteWhenSystemIsOff
Access the control panel accessCp
↳ Access the control panel when the system is offline accessCpWhenSystemIsOff
↳  Perform Craft CMS and plugin updates performUpdates
↳  Access
Plugin Name
Edit users editUsers
↳  Register users registerUsers
↳  Moderate users moderateUsers
↳  Administrate users administrateUsers
↳  Impersonate users
↳  Assign user permissions assignUserPermissions
↳  Assign users to this group
See note.
↳  Assign users to
Group Name
Delete users deleteUsers
Site Name
View entries
↳  Create entries createEntries:[SectionUID]
↳  Save entries saveEntries:[SectionUID]
↳  Delete entries deleteEntries:[SectionUID]
↳  View other users’ entries viewPeerEntries:[SectionUID]
    ↳  Save other users’ entries savePeerEntries:[SectionUID]
    ↳  Delete other users’ entries deletePeerEntries:[SectionUID]
↳ View other users’ drafts viewPeerEntryDrafts:[SectionUID]
    ↳  Save other users’ drafts savePeerEntryDrafts:[SectionUID]
    ↳  Delete other users’ drafts deletePeerEntryDrafts:[SectionUID]
Global Set Name
View categories
↳  Save categories saveCategories:[CategoryGroupUID]
↳  Delete categories deleteCategories:[CategoryGroupUID]
↳  View other users’ drafts viewPeerCategoryDrafts:[CategoryGroupUID]
    ↳  Save other users’ drafts savePeerCategoryDrafts:[CategoryGroupUID]
    ↳  Delete other users’ drafts deletePeerCategoryDrafts:[CategoryGroupUID]
View assets viewAssets:[VolumeUID]
↳  Save assets saveAssets:[VolumeUID]
↳  Delete assets deleteAssets:[VolumeUID]
↳  Replace files replaceFiles:[VolumeUID]
↳  Edit images editImages:[VolumeUID]
↳  View assets uploaded by other users viewPeerAssets:[VolumeUID]
    ↳  Save assets uploaded by other users savePeerAssets:[VolumeUID]
    ↳  Replace files uploaded by other users replacePeerFiles:[VolumeUID]
    ↳  Remove files uploaded by other users deletePeerAssets:[VolumeUID]
    ↳  Edit images uploaded by other users editPeerImages:[VolumeUID]
↳  Create subfolders createFolders:[VolumeUID]
↳  Updates utility:updates
↳  System Report utility:system-report
↳  PHP Info utility:php-info
↳  System Messages utility:system-messages
↳  Asset Indexes utility:asset-indexes
↳  Queue Manager utility:queue-manager
↳  Caches utility:clear-caches
↳  Deprecation Warnings utility:deprecation-errors
↳  Database Backup utility:db-backup
↳  Find and Replace utility:find-replace
↳  Migrations utility:migrations

You may not see all of these options, initially—only ones that are relevant based on the current content schema will be displayed. For example, everything under View categories will be hidden until you have at least one category group.

Plugins may register their own permissions, which can appear in a top-level group, under Access the control panel, or within Utilities.

See the Extending Craft User Permissions page to learn how to register custom permissions from your module or plugin.

# Checking Permissions

You can check whether the logged-in user has a specific permission by using its handle, replacing any bracketed items in the table above with the desired value (So accessPlugin-[PluginHandle] would become accessPlugin-commerce).

{% if currentUser.can('accessCp') %}
  <a href="{{ cpUrl() }}">Visit the Control Panel</a>
{% endif %}

For UUID-driven permissions, you can either hard-code the value in Twig, or look it up dynamically.

{# Store the UUID directly in the template: #}
{% if currentUser.can('createEntries:4fcb3c63-9477-4b5f-8021-874d64f819ce') %}
  <a href="{{ siteUrl('account/vendors/add') }}">Add a Vendor</a>
{% endfor %}

This is not strictly necessary, but the handle of a given resource is often much easier to understand in the template context.

UUIDs and handles are safe to use like this because they’re tracked in Project Config and will be consistent across environments, unlike IDs.

If your site or app doesn’t rely on specific permissions to control access to certain resources, you can check whether the user belongs to a group, instead:


{% requireLogin %}

{% if currentUser.isInGroup('members') %}
  <div class="banner">Thanks for your support!</div>
{% endif %}

# Requiring Permissions

You can also require the logged-in user to have a specific permission to access an entire template:

{% requirePermission 'accessCp' %}

If the requirements are not met, Craft will send a 403 Forbidden response with the site’s error template. Logged-out visitors will be forwarded to the configured loginPath; after signing in, the user will be redirected to the original path—but may still encounter a Forbidden error if their account doesn’t have the correct permissions.

# Forms + Content

When a user is given permissions to edit or create elements that meet certain criteria (say, entries in a specific section), they do not need control panel access to make updates.

When POSTing new data to actions like entries/save-entry (or the more generic elements/save), Craft makes sure the user has the appropriate permissions. This means that you can create secure, streamlined content management tools for users, without ever granting them access to the control panel!

# Querying by Permissions

You can look up users with a given permission using the can() method on a user query. To find users belonging to a specific group, use the group() method.

# Authentication New!

Credentialed users in Craft can authenticate with one or more methods. By default, Craft uses a password to verify the user’s identity. In addition to passwords, users can set up two-factor authentication, or add a passkey.

Two-factor authentication setup screen in the Craft control panel

Plugins can also provide authentication methods!

# Time-based, One-Time Passwords

Craft has built-in support for one-time passwords via your favorite authenticator app or password manager. When enabled (via

  1. Settings
  2. Users
  3. Security
), control panel users subject to your policy will be asked to set up an authenticator on their next login.

If a user loses access to their TOTP provider, they can use one of the recovery codes generated at the time it was set up.

# Passkeys

Individual users can elect to log in with a Passkey (opens new window). To configure a passkey, visit your user’s account screen via the menu in the upper-right corner of the control panel, then choose Passkeys.

Some browsers and devices share passkeys via their own accounts or cloud services, so you may only need one passkey added to Craft to authenticate on multiple devices.

# Public Registration Pro

Public user registration is disabled by default, but can be turned on in any Craft Pro project.

To enable public registration, go to SettingsUsersSettings, and check Allow public registration. With that checked, you will also have the ability to choose a Default User Group that publicly-registered users will be automatically added to.

Once you set up your site to allow public user registration, the last step is to create a front-end user registration form (opens new window). For a full list of params a user can set during registration (or when updating their account, later on), read about the users/save-user controller action.

By default, Craft puts new users in a pending state and allows them to activate their own accounts via email. You can instead select Deactivate users by default to place a moderation buffer between public registration and eventual access.

# Default Group

Users created via public registration are automatically added to the group designated by the Default User Group setting.

Select this group’s permissions carefully, ensuring that new users don’t immediately get access to tools that can negatively affect other users’ experience.


Craft’s command line provides admin-level user management tools. With access to the underlying server, you can create, delete, and impersonate users, get activation URLs, set passwords, and even log out all users.

Users CLI Reference
Read more about managing users via the command line.