---
title: "Role Management"
description: "This page explains the procedures for various role management tasks under TigerGraph's role-based access control model."
component: "tigergraph-server"
version: "4.3"
module: "user-access"
html_url: "/tigergraph-server/4.3/user-access/role-management"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/role-management"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/role-management.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/role-management)

# Role Management

This page explains the procedures for various role management tasks under TigerGraph's classic role-based access control model.

> [!NOTE]
> **Known Issue**: usernames beginning with a digit or containing non-alphanumeric characters cannot grant or revoke privileges.

For Row Policy and Object-Based privilege management, see[RBAC Row Policy Overview](https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/rbac-row-policy/row-policy-overview.md).

## Create a local role

> [!NOTE]
> Local roles are deprecated and will be dropped in a future release.

### Syntax

```gsql
CREATE ROLE <role_name> (, <role_name>)* [ON GRAPH <graph_name>]
```

### Required privilege

`WRITE_ROLE`

### Example

1. To create a local role, run the `CREATE ROLE` command like below. If you choose not to specify a graph in the command, the current scope will be used as the scope of the role:  
```gsql  
GSQL > USE GRAPH example_graph  
GSQL > CREATE ROLE role1, role2  
```

This will create two roles named `role1` and `role2` on graph `example_graph`. By default, these two roles do not have any privilege:

Successfully created local roles for graph 'example_graph': [role1, role2].

## Create a global role

You can create a global role with the `CREATE ROLE` command.

### Syntax

```gsql
CREATE ROLE <role_name> (, <role_name>)* ON GLOBAL
```

### Required privilege

`WRITE_ROLE` on the global scope

### Example

1. To create a global role, run the `CREATE ROLE` command like below. Replace `role1` with the name of the role you are creating.

```gsql
CREATE ROLE role1 ON GLOBAL
```

This will create a role named `role1` on the global scope. By default, this role has no privileges:

```console
Successfully created global roles: [role1].
```

## View privileges of a role

Users with the `READ_ROLE` privilege in a scope can view the privileges on the roles in that scope.

Both `SHOW GRANTS TO ROLE` and `SHOW PRVILEGE ON ROLE` shows the RBAC privileges of a role.

### Syntax

```gsql
SHOW PRIVILEGE ON ROLE <role_name>, <role_name2> ...
```

```gsql
SHOW GRANTS TO ROLE <role_name1>, <role_name2> ...
```

### Required privilege

`READ_ROLE` on the global scope

### Example

The following command shows all privileges of the role `moderator`:

```text
GSQL > USE GLOBAL
GSQL > SHOW GRANTS TO ROLE moderator
RBAC privileges of Role: "moderator"
- Global Privileges:
READ_DATA
- Graph 'Social' Privileges:
- Type 'Person' Privileges:
CREATE_DATA
- Attribute 'locationIP' Privileges:
UPDATE_DATA
```

The following command shows all privileges of the roles `role1` and `role2`:

```gsql
GSQL > SHOW PRIVILEGE ON ROLE role1 , role2
```

## View all users who are assigned a role

You can specify a role and view all users who are assigned that role.

### Syntax

```gsql
SHOW GRANTS OF ROLE <role_name1>, <role_name2> ...
```

### Required privilege

`READ_ROLE` and `READ_USER` on global scope

### Example

The following command shows all users with the role `moderator`:

```gsql
GSQL > SHOW GRANTS OF ROLE moderator
Users with role moderator:
  tigergraph
```

## List all existing roles

### Syntax

```gsql
SHOW ROLE
```

### Required privilege

`READ_ROLE`

### Example

1. To list all existing roles, first ensure that you are in the correct scope. Run `USE <graph_name>` or `USE GLOBAL` to switch to your desired scope.
2. Run the `SHOW ROLE` command:  
```gsql  
GSQL > SHOW ROLE  
```

This will show all the roles in your current scope:

```text
  - Builtin Roles:
    observer
    queryreader
    querywriter
    designer
    admin
    globaldesigner
    superuser

  - User Defined Roles:
    - Graph 'tpc_graph' Roles:
      role1
      role2
```

## Grant privileges to a role

Users with the `WRITE_ROLE` privileges on a scope can grant RBAC privileges to the roles in that scope.

> [!NOTE]
> **Known Issue**: usernames beginning with a digit or containing non-alphanumeric characters cannot grant or revoke privileges.

### Syntax

```text
GRANT <privilege_name1> (, <privilege_name2>)*
ON (GLOBAL | ALL <object_type_plural1> (, ALL <object_type_plural2>)* | <object_type> <object_name1> ((, <object_name2>)* | <attribute_type> <attribute_name1> (, <attribute_name2>)*)?)
IN [GRAPH <graph_name>|GLOBAL] TO <role_name1> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

1. To grant privileges to a role, run the Object-based grant privilege command from the GSQL shell:  
```text  
GSQL > GRANT WRITE ON ALL QUERIES, ALL ROLES  
        IN GRAPH example_graph TO role1 , role2  
```

This will allow users with the roles `role1` and `role2` to create, read, update, drop, install and execute existing queries, as well as modify roles on the graph `example_graph`. For more information on query privileges, see [Fine-Grained Query Privileges](https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/fine-grained-query-privileges.md).

## Grant type-level privilege to a role

You can grant certain privileges (`READ_DATA`, `CREATE_DATA`, `DELETE_DATA`, `UPDATE_DATA`) on a type level to the roles in that scope. The privilege only applies to the specified types.

### Syntax

```gsql
GRANT <privilege_name1> (, <privilege_name2>)* ON [VERTEX|EDGE] <type_name1> (, <type_name2>)* IN [GRAPH <graph_name>|GLOBAL] TO <role_name> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE` and the privilege being granted

### Example

The following command grants the `READ_DATA` and `CREATE_DATA` privilege on vertex type `Person` to `role1` and `role2`.

```gsql
GRANT READ, CREATE ON VERTEX Person IN GRAPH G1 TO role1, role2
```

This allows users with `role1` and `role2` to read all attribute values of type `Person` vertices. However, to insert new vertices, the user must also have `UPDATE_DATA` on all attributes of vertex type `Person`.

## Grant attribute-level privilege to a role

You can grant certain privileges (`READ_DATA`, `CREATE_DATA`, `UPDATE_DATA`) on an attribute level to a role. The privilege only applies to the specified attributes of the specified type.

### Syntax

```gsql
GRANT <privilege_name1> (, <privilege_name2>)* ON [VERTEX|EDGE] <type_name> ATTRIBUTE <attribute_name1> (, <attribute_name2>)* IN [GRAPH <graph_name>|GLOBAL] TO <role_name> (, <role_name2>)*
```

`from` and `to` are edge attributes that represent the source vertex and target vertex of an edge. When you grant access to these attributes, `from` and `to` are case-sensitive. You must use lower-case to indicate these two attributes.

### Required privilege

`WRITE_ROLE` and the privilege being granted

### Example

The following command grants the `READ_DATA` privilege on the `id` and `age` attribute of the vertex type `Person` to `example_role`.

```gsql
GRANT READ ON VERTEX person ATTRIBUTE id, age IN GRAPH G1 TO example_role
```

This allows users with `example_role` to read the `id` and `age` attribute values of `Person` vertices. However, if the type `Person` has other attributes, such as an `SSN` attribute with their social security number, users who don't have the `READ_DATA` privilege on that attribute are not able to access its attribute value.

The following command grants the `READ_DATA` privilege on the `to` attribute of the edge type `Knows` to `example_role`:

```gsql
GRANT READ ON EDGE Knows ATTRIBUTE to IN GRAPH ldbc_snb TO example_role (1)
```

| **1** | `to` must be lower-case. |
| --- | --- |

## Revoke privileges from a role

Users with the `WRITE_ROLE` privileges on a scope can revoke RBAC privileges from the roles in that scope.

### Syntax

```text
REVOKE <privilege_name1> (, <privilege_name2>)*
ON (GLOBAL | ALL <object_type_plural1> (, ALL <object_type_plural2>)* | <object_type> <object_name1> ((, <object_name2>)* | <attribute_type> <attribute_name1> (, <attribute_name2>)*)?)
IN [GRAPH <graph_name> | GLOBAL]
FROM <role_name1> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

1. To revoke privileges from a role, run the Object-based revoke privilege command from the GSQL shell:  
```text  
GSQL > REVOKE WRITE ON ALL SCHEMA  
        IN GRAPH example_graph FROM role1  
```

This will revoke the `WRITE_SCHEMA` privilege from the role `role1` on graph `example_graph.`

## Revoke type-level privileges

You can revoke certain privileges from the type level with the Object-based revoke privilege command.

Revoking a privilege at the type does not affect privileges granted at higher levels (e.g., global or graph level). For instance, if a role has `` READ_DATA` `` on a vertex type globally, revoking this privilege at the type level will not prevent the role from accessing the vertex type.

### Syntax

```gsql
REVOKE <privilege_name1> (, <privilege_name2>)* ON [VERTEX|EDGE] <type_name> (, <type_name2>)* IN [GRAPH <graph_name>|GLOBAL] FROM <role_name> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

The following command revokes the `UPDATE_DATA` privilege on type `Friendship` from `role1`, and `role2`:

```gsql
REVOKE UPDATE ON EDGE Friendship IN GRAPH Social FROM role1, role2
```

## Revoke attribute-level privileges

You can revoke certain privileges from the attribute level with the Object-based revoke privilege command.

Revoking a privilege at the type does not affect privileges granted at higher levels (e.g., global, graph level or type level). For instance, if a role has `` READ_DATA` `` on a vertex type globally, revoking this privilege at the attribute level will not prevent the role from accessing the vertex attribute type.

### Syntax

```gsql
REVOKE <privilege_name1> (, privilege_name2)* ON [VERTEX|EDGE] <type_name> ATTRIBUTE <attribute1> (, <attribute2>)* FROM <role_name> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE` and the privilege being granted

### Example

The following command revokes `CREATE_DATA` and `UPDATE_DATA` on the `startdata` attribute from `role1` and `role2`.

If the user doesn't have these privileges, they are not able to create new edges of type `Friendship`.

```gsql
REVOKE CREATE, UPDATE ON EDGE Friendship ATTRIBUTE startdata IN GRAPH Social FROM role1, role2
```

## Grant default roles

Use `GRANT DEFAULT` to add one or more user-defined roles to the default list for a specific query-level privilege.

### Syntax

```gsql
GRANT DEFAULT <privilege_name1> (, <privilege_name2>)*
ON ALL QUERIES
IN GRAPH <graph_name> TO <role_or_user_name1> (, <role_or_user_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

1. The following command grants default `READ` privileges on all newly created queries in a graph to a specified role:  
```gsql  
GSQL > GRANT DEFAULT READ ON ALL QUERIES IN GRAPH MyGraph TO ROLE analytics_reader  
```  
This allows `analytics_reader` to automatically receive query-level `READ` access on any new query created in `MyGraph`, without requiring additional `GRANT` commands.
2. The following command grants default `EXECUTE` privileges on all newly created queries in a graph to multiple roles:  
```gsql  
GSQL > GRANT DEFAULT EXECUTE ON ALL QUERIES IN GRAPH MyGraph TO ROLE data_scientist, app_service  
```  
This allows `data_scientist` and `app_service` to automatically receive query-level `EXECUTE` access on any new query created in `MyGraph`, without requiring additional `GRANT` commands.

## Revoke default roles

Use `REVOKE DEFAULT` to remove roles from the default list for a specific query-level privilege.

### Syntax

```gsql
REVOKE DEFAULT <privilege_name1> (, <privilege_name2>)*
ON ALL QUERIES
IN GRAPH <graph_name> FROM <role_or_user_name1> (, <role_or_user_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

1. The following command revokes default `READ` privileges on all newly created queries in a graph from a specified role:  
```gsql  
GSQL > REVOKE DEFAULT READ ON ALL QUERIES IN GRAPH MyGraph FROM ROLE analytics_reader  
```  
This prevents `analytics_reader` from automatically receiving query-level `READ` access on any new query created in `MyGraph`. Existing queries where `analytics_reader` already has `READ` remain unchanged.

## Show default roles

Use `SHOW DEFAULT ROLES` to inspect which roles are currently configured as defaults for each supported query-level privilege.

### Syntax

```gsql
SHOW DEFAULT ROLES (IN GRAPH <graph_name>)?
```

### Required privilege

`READ_ROLE`

### Example

1. The following command shows which roles currently receive default query-level privileges in `MyGraph`:  
```gsql  
GSQL > SHOW DEFAULT ROLES IN GRAPH MyGraph  
```  
This displays all roles and users configured to automatically receive `READ` or `EXECUTE` privileges on newly created queries in `MyGraph`.

## Drop a role

### Syntax

```text
DROP ROLE <role_name> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

1. To drop a role, run the `DROP ROLE` command from the GSQL shell:  
```text  
GSQL > DROP ROLE role1 , role2  
```

This will drop the roles `role1` and `role2`. This will also revoke the roles from users who have been granted these roles.
