Skip to content
Return to top
On this page

# Roles #

> Roles define a specific set of access permissions, and are the primary organizational structure for Users within the platform. Learn more about Roles.

## The Role Object #

`id` uuid
Primary key of the role.

`name` string
Name of the role.

`icon` string
Icon for the role. Displayed in the Admin App.

`description` string
Description for the role. Displayed in the Admin App.

`ip_access` csv
A CSV of IP addresses that have access to this role. Allows you to configure an allowlist of IP addresses.

`enforce_tfa` boolean
Whether or not Two-Factor Authentication is required for users in this role.

`admin_access` boolean
If this role is considered an admin role. This means that users in this role have full permissions to everything.

`app_access` boolean
Whether or not users in this role have access to use the Admin App.

`users` one-to-many
The users in this role. One-to-many to users.

json

    {
    	"id": "653925a9-970e-487a-bfc0-ab6c96affcdc",
    	"name": "Admin",
    	"icon": "supervised_user_circle",
    	"description": null,
    	"ip_access": null,
    	"enforce_tfa": false,
    	"admin_access": true,
    	"app_access": true,
    	"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
    }

## List Roles #

List all roles that exist in Directus.

### Query Parameters #

Supports all global query parameters.

### Returns #

An array of up to limit role objects. If no items are available, data will be an empty array.

### REST API #

    GET /roles
    SEARCH /roles

Learn more about SEARCH ->

### GraphQL #

    POST /graphql/system

graphql

    type Query {
    	roles: [directus_roles]
    }

##### Example #

graphql

    query {
    	roles {
    		id
    		name
    		users {
    			email
    		}
    	}
    }

## Retrieve a Role #

List an existing role by primary key.

### Query Parameters #

Supports all global query parameters.

### Returns #

Returns the requested role object.

### REST API #

    GET /roles/:id

##### Example #

    GET /roles/b4cb3b64-8580-4ad9-a099-eade6da24302

### GraphQL #

    POST /graphql/system

graphql

    type Query {
    	roles_by_id(id: ID!): directus_roles
    }

##### Example #

graphql

    query {
    	roles_by_id(id: 2) {
    		id
    		name
    		users {
    			email
    		}
    	}
    }

## Create a Role #

Create a new role.

### Query Parameters #

Supports all global query parameters.

### Request Body #

A partial role object.

### Returns #

Returns the role object for the created role.

### REST API #

    POST /roles

##### Example #

json

    // POST /roles

    {
    	"name": "Interns",
    	"icon": "verified_user",
    	"description": null,
    	"admin_access": false,
    	"app_access": true
    }

### GraphQL #

    POST /graphql/system

graphql

    type Mutation {
    	create_roles_item(data: create_directus_roles_input!): directus_roles
    }

##### Example #

graphql

    mutation {
    	create_roles_item(
    		data: { name: "Interns", icon: "verified_user", description: null, admin_access: false, app_access: true }
    	) {
    		id
    		name
    		users {
    			email
    		}
    	}
    }

## Create Multiple Roles #

Create multiple new roles.

### Query Parameters #

Supports all global query parameters.

### Request Body #

An array of partial role objects.

### Returns #

Returns the role objects for the created roles.

### REST API #

    POST /roles

##### Example #

json

    // POST /roles

    [
    	{
    		"name": "Interns",
    		"icon": "verified_user",
    		"description": null,
    		"admin_access": false,
    		"app_access": true
    	},
    	{
    		"name": "Customers",
    		"icon": "person",
    		"description": null,
    		"admin_access": false,
    		"app_access": false
    	}
    ]

### GraphQL #

    POST /graphql/system

graphql

    type Mutation {
    	create_roles_items(data: [create_directus_roles_input!]!): [directus_roles]
    }

##### Example #

graphql

    mutation {
    	create_roles_items(
    		data: [
    			{ name: "Interns", icon: "verified_user", description: null, admin_access: false, app_access: true }
    			{ name: "Customers", icon: "person", description: null, admin_access: false, app_access: false }
    		]
    	) {
    		id
    		name
    		users {
    			email
    		}
    	}
    }

## Update a Role #

Update an existing role.

### Query Parameters #

Supports all global query parameters.

### Request Body #

A partial role object.

### Returns #

Returns the role object for the updated role.

### REST API #

    PATCH /roles/:id

##### Example #

json

    // PATCH /roles/c86c2761-65d3-43c3-897f-6f74ad6a5bd7

    {
    	"icon": "attractions"
    }

### GraphQL #

    POST /graphql/system

graphql

    type Mutation {
    	update_roles_item(id: ID!, data: update_directus_roles_input): directus_roles
    }

##### Example #

graphql

    mutation {
    	update_roles_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", data: { icon: "attractions" }) {
    		id
    		name
    		users {
    			email
    		}
    	}
    }

## Update Multiple Roles #

Update multiple existing roles.

### Query Parameters #

Supports all global query parameters.

### Request Body #

`keys` Required
Array of primary keys of the roles you'd like to update.

`data` Required
Any of the role object's properties.

### Returns #

Returns the role objects for the updated roles.

### REST API #

    PATCH /roles

##### Example #

json

    // PATCH /roles

    {
    	"keys": ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"],
    	"data": {
    		"icon": "attractions"
    	}
    }

### GraphQL #

    POST /graphql/system

graphql

    type Mutation {
    	update_roles_items(ids: [ID!]!, data: update_directus_roles_input): [directus_roles]
    }

##### Example #

graphql

    mutation {
    	update_roles_items(
    		ids: ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"]
    		data: { icon: "attractions" }
    	) {
    		id
    		name
    		users {
    			email
    		}
    	}
    }

## Delete a Role #

Delete an existing role.

### Returns #

Empty body.

### REST API #

    DELETE /roles/:id

##### Example #

    DELETE /roles/c86c2761-65d3-43c3-897f-6f74ad6a5bd7

### GraphQL #

    POST /graphql/system

graphql

    type Mutation {
    	delete_roles_item(id: ID!): delete_one
    }

##### Example #

graphql

    mutation {
    	delete_roles_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7") {
    		id
    	}
    }

## Delete Multiple Roles #

Delete multiple existing roles.

### Request Body #

An array of role primary keys

### Returns #

Empty body.

### REST API #

    DELETE /roles

##### Example #

json

    // DELETE /roles
    ["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]

### GraphQL #

    POST /graphql/system

graphql

    type Mutation {
    	delete_roles_items(ids: [ID!]!): delete_many
    }

##### Example #

graphql

    mutation {
    	delete_roles_items(ids: ["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]) {
    		ids
    	}
    }