# # 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
- List Roles
- Retrieve a Role
- Create a Role
- Create Multiple Roles
- Update a Role
- Update Multiple Roles
- Delete a Role
- Delete Multiple 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
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.

    {
    	"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

    type Query {
    	roles: [directus_roles]
    }

##### # Example

    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

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

##### # Example

    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

    // POST /roles

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

### # GraphQL

    POST /graphql/system

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

##### # Example

    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

    // 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

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

##### # Example

    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

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

    {
    	"icon": "attractions"
    }

### # GraphQL

    POST /graphql/system

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

##### # Example

    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

    // PATCH /roles

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

### # GraphQL

    POST /graphql/system

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

##### # Example

    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

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

##### # Example

    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

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

### # GraphQL

    POST /graphql/system

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

##### # Example

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