Manage roles
AuraDB Business CriticalAuraDB Virtual Dedicated CloudEnterprise Edition

Roles can be created and managed using a set of Cypher administration commands executed against the system database.

When connected to the DBMS over bolt, administration commands are automatically routed to the system database.

Role management command syntax

For more details about the syntax descriptions, see Database management command syntax.
Table 1. SHOW ROLES command syntax

Command

SHOW ROLES

Syntax

 
SHOW [ALL|POPULATED] ROLE[S]
  [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
  [WHERE expression]
  [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

Lists roles.

When using the RETURN clause, the YIELD clause is mandatory and must not be omitted.

For more information, see Listing roles.

Required privilege

 
GRANT SHOW ROLE

See DBMS ROLE MANAGEMENT privileges.
Table 2. SHOW ROLES WITH USERS command syntax

Command

SHOW ROLES WITH USERS

Syntax

 
SHOW [ALL|POPULATED] ROLE[S] WITH USER[S]
  [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
  [WHERE expression]
  [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

Lists roles and users assigned to them.

When using the RETURN clause, the YIELD clause is mandatory and must not be omitted.

For more information, see Listing roles.

Required privilege

 
GRANT SHOW ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.

GRANT SHOW USER

For more information, see DBMS USER MANAGEMENT privileges.
Table 3. SHOW ROLES WITH AUTH RULES command syntax
Introduced in 2026.03

Command

SHOW ROLES WITH AUTH RULES

Syntax

 
SHOW [ALL|POPULATED] ROLE[S] WITH AUTH RULE[S]
  [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
  [WHERE expression]
  [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

Lists roles and auth rules assigned to them.

When using the RETURN clause, the YIELD clause is mandatory and must not be omitted.

For more information, see Listing roles.

Required privilege

 
GRANT SHOW ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.

GRANT SHOW AUTH RULE

For more information, see DBMS AUTH RULE MANAGEMENT privileges.
Table 4. SHOW ROLE PRIVILEGES command syntax

Command

SHOW ROLE PRIVILEGES

Syntax

 
SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]]
  [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
  [WHERE expression]
  [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

Lists the privileges granted to the specified roles.

When using the RETURN clause, the YIELD clause is mandatory and must not be omitted.

The SHOW ROLE name PRIVILEGES command is described in Listing privileges.

Required privilege

 
GRANT SHOW PRIVILEGE

See DBMS PRIVILEGE MANAGEMENT privileges.
Table 5. CREATE [IMMUTABLE] ROLE command syntax

Command

CREATE [IMMUTABLE] ROLE

Syntax

 
CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName]

Description

Creates a new role.

For more information, see Creating roles.

Required privilege

 
GRANT CREATE ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.
Table 6. CREATE OR REPLACE [IMMUTABLE] ROLE command syntax

Command

CREATE OR REPLACE [IMMUTABLE] ROLE

Syntax

 
CREATE OR REPLACE [IMMUTABLE] ROLE name [AS COPY OF otherName]

Description

Creates a new role, or if a role with the same name exists, replace it.

For more information, see Creating roles.

Required privilege

 
GRANT CREATE ROLE
GRANT DROP ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.
Table 7. RENAME ROLE command syntax

Command

RENAME ROLE

Syntax

 
RENAME ROLE name [IF EXISTS] TO otherName

Description

Changes the name of a role.

For more information, see Renaming roles.

Required privilege

 
GRANT RENAME ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.
Table 8. DROP ROLE command syntax

Command

DROP ROLE

Syntax

 
DROP ROLE name [IF EXISTS]

Description

Removes a role.

For more information, see Deleting roles.

Required privilege

 
GRANT DROP ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.
Table 9. GRANT ROLE TO command syntax

Command

GRANT ROLE TO

Syntax

 
GRANT ROLE[S] name[, ...]
TO {AUTH RULE[S] authrule[, ...] | [USER[S]] user[, ...]}

Description

Assigns roles directly to users or indirectly through attribute-based access control auth rules.

For more information on assigning roles to users, see Assigning roles to users.

For more information on assigning roles to auth rules, see Assigning roles to auth rules.

Required privilege

 
GRANT ASSIGN ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.
Table 10. REVOKE ROLE command syntax

Command

REVOKE ROLE

Syntax

 
REVOKE ROLE[S] name[, ...]
FROM {AUTH RULE[S] authrule[, ...] | [USER[S]] user[, ...]}

Description

Removes roles from users or attribute-based access control auth rules.

For more information on revoking roles from users, see Revoking roles from users.

For more information on revoking roles from auth rules, see Revoking roles from auth rules.

Required privilege

 
GRANT REMOVE ROLE

For more information, see DBMS ROLE MANAGEMENT privileges.

Listing roles

You can view all available roles using the Cypher command SHOW ROLES, which returns a single column by default. Optionally, you can also use SHOW ROLES YIELD * to see if the role is immutable. See Immutable roles for more information.

Table 11. SHOW ROLES output
Column Description Type

role

Role name

STRING

immutable

true if the role is immutable, otherwise false.

BOOLEAN

Listing all roles

To list all roles, use the SHOW ROLES command:

SHOW ROLES

This is the same command as SHOW ALL ROLES.

Table 12. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"publisher"

"reader"

Rows: 6

When first starting a Neo4j DBMS, there are a number of built-in roles:

  • PUBLIC - a role that all users have granted. By default it gives access to the home database and to execute privileges for procedures and functions.

  • reader - can perform traverse and read operations in all databases except system.

  • editor - can perform traverse, read, and write operations in all databases except system, but cannot create new labels or relationship types.

  • publisher - can do the same as editor, but also create new labels and relationship types.

  • architect - can do the same as publisher as well as create and manage indexes and constraints.

  • admin - can do the same as all the above, as well as manage databases, aliases, users, roles, and privileges.

More information about the built-in roles and their privileges can be found in Built-in roles and privileges.

There are multiple versions of this command, the default being SHOW ALL ROLES. To only show roles that are assigned to users or auth rules, the command is SHOW POPULATED ROLES. This returns the same output columns as SHOW ROLES.

Listing users assigned to roles

To see which users are assigned to which roles, you can add WITH USERS to the command.

SHOW POPULATED ROLES WITH USERS

The command produces a row per role per user and yields a member column, in addition to the one returned by SHOW ROLES, containing the name of the user assigned to the role, or null if the role is not assigned to any users. If a role is assigned to multiple users, it will appear once for each user.

Table 13. Result
role member

"PUBLIC"

"neo4j"

"PUBLIC"

"bob"

"PUBLIC"

"user1"

"PUBLIC"

"user2"

"PUBLIC"

"user3"

"admin"

"neo4j"

Rows: 6

Listing auth rules assigned to roles
Introduced in 2026.03

To see which auth rules are assigned to which roles, add WITH AUTH RULES to the command:

SHOW POPULATED ROLES WITH AUTH RULES

The command produces a row per role per auth rule and yields an authRule column, in addition to the one returned by SHOW ROLES, containing the name of the auth rule assigned to the role, or null if the role is not assigned to any auth rules. If a role is assigned to multiple auth rules, it will appear once for each auth rule.

Table 14. Result
role authRule

"PUBLIC"

null

"admin"

"adminRule"

Rows: 6

Filtering and ordering roles results

You can filter and sort the results by using YIELD, ORDER BY, and WHERE:

SHOW ROLES YIELD role
ORDER BY role
WHERE role ENDS WITH 'r'

In this example:

  • The results are filtered to return only roles ending in 'r'.

  • The results are ordered by the role column using ORDER BY.

It is also possible to use SKIP and LIMIT to paginate the results.

Table 15. Result
role

"editor"

"publisher"

"reader"

Rows: 3

Creating roles

There are different ways to create roles, depending on your needs.

The following naming rules apply to all roles created in Neo4j:

  • The first character must be an ASCII alphabetic character.

  • Subsequent characters can be ASCII alphabetic, numeric characters, and underscore.

  • Role names are case sensitive.

Creating new roles

You can create roles using CREATE [IMMUTABLE] ROLE:

CREATE [IMMUTABLE] ROLE name [IF NOT EXISTS] [AS COPY OF otherName]

The CREATE ROLE command is optionally idempotent, with the default behavior to throw an exception if the role already exists. Adding IF NOT EXISTS to the CREATE ROLE command ensures that no exception is thrown and nothing happens should the role already exist.

CREATE ROLE myrole IF NOT EXISTS

Creating new roles with the same privileges as existing roles

You can copy a role, keeping its privileges, using CREATE [IMMUTABLE] ROLE name AS COPY OF otherName:

CREATE ROLE mysecondrole AS COPY OF myrole

The created roles appear on the list provided by SHOW ROLES:

SHOW ROLES
Table 16. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"mysecondrole"

"publisher"

"reader"

Rows: 8

Creating new roles or replacing existing roles

You can create or replace roles by using CREATE OR REPLACE [IMMUTABLE] ROLE:

CREATE OR REPLACE [IMMUTABLE] ROLE name [AS COPY OF otherName]

The CREATE OR REPLACE ROLE command results in any existing role being deleted and a new one created.
For example:

CREATE OR REPLACE ROLE myrole

The command CREATE OR REPLACE ROLE myrole will delete the existing myrole and create a new one with the same name. This is equivalent to running DROP ROLE myrole IF EXISTS followed by CREATE ROLE myrole.

The CREATE OR REPLACE ROLE command does not allow you to use the IF NOT EXISTS.

Immutable roles

Immutable roles are roles that cannot be modified in the usual way. This means they cannot be created, renamed, dropped, or have privileges granted to or revoked from them under normal operating conditions. See Immutable roles and privileges for details of when and how the IMMUTABLE keyword may be used.

They are useful in cases where you need a permanent built-in system role that cannot be modified even by users who have ROLE MANAGEMENT privileges but yet can be granted to and revoked from users in the same way as an ordinary role.

Renaming roles

You can rename a role using RENAME ROLE command:

RENAME ROLE mysecondrole TO mythirdrole

After renaming a role, the new name will appear on the list provided by SHOW ROLES:

SHOW ROLES
Table 17. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"mythirdrole"

"publisher"

"reader"

Rows: 8

The RENAME ROLE command is only available when using native authentication and authorization.

Assigning roles to users

This section explains how roles can be directly granted to users. For information on how roles can be assigned to users based on attribute-based rules, see Attribute-based access control.

Assigning a role to a user

Users can be given access rights by assigning them roles using GRANT ROLE:

GRANT ROLE myrole TO bob

The roles assigned to each user can be seen on the list provided by SHOW USERS:

SHOW USERS
Table 18. Result
user roles passwordChangeRequired suspended home

"bob"

["myrole","PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

"user1"

["PUBLIC"]

true

false

<null>

"user2"

["PUBLIC"]

true

false

<null>

"user3"

["PUBLIC"]

true

false

<null>

Rows: 5

Assigning multiple roles to multiple users

You can assign multiple roles to multiple users in one command:

GRANT ROLES role1, role2 TO user1, user2, user3
SHOW USERS
Table 19. Result
user roles passwordChangeRequired suspended home

"bob"

["myrole","PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

"user1"

["role1","role2","PUBLIC"]

true

false

<null>

"user2"

["role1","role2","PUBLIC"]

true

false

<null>

"user3"

["role1","role2","PUBLIC"]

true

false

<null>

Rows: 5

Common errors, such as attempts to grant roles to users who have already been granted those roles, will lead to notifications. Some of these notifications may be replaced with errors in a future major version of Neo4j. See Status Codes for Errors & Notifications → List of notification codes for details on notifications.

Revoking roles from users

This section explains how roles can be directly revoked from users. For information on how roles can be revoked from users based on attribute-based rules, see Attribute-based access control.

Revoking a role from a user

Users can lose access rights by revoking their role using REVOKE ROLE:

REVOKE ROLE myrole FROM bob

The roles revoked from users can no longer be seen on the list provided by SHOW USERS:

SHOW USERS
Table 20. Result
user roles passwordChangeRequired suspended home

"bob"

["PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

"user1"

["role1","role2","PUBLIC"]

true

false

<null>

"user2"

["role1","role2","PUBLIC"]

true

false

<null>

"user3"

["role1","role2","PUBLIC"]

true

false

<null>

Rows: 5

Revoking multiple roles from multiple users

You can revoke multiple roles from multiple users in one command:

REVOKE ROLES role1, role2 FROM user1, user2, user3

Common errors, such as misspellings or attempts to revoke roles from users who have not been granted those roles, will lead to notifications. In Cypher 25, notifications for impossible REVOKE commands, where a user, a role, or a database does not exist, have been replaced with errors. See Status Codes for Errors & Notifications → List of notification codes for details on notifications.

Deleting roles

You can delete roles that are no longer needed using the DROP ROLE command:

DROP ROLE mythirdrole

Deleting a role removes it from the list provided by SHOW ROLES:

SHOW ROLES
Table 21. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"publisher"

"reader"

Rows: 8

This command is optionally idempotent, with the default behavior to throw an exception if the role does not exist. Adding IF EXISTS to the command will ensure that no exception is thrown and nothing happens should the role not exist:

DROP ROLE mythirdrole IF EXISTS