Appearance

On this page

Permissions ​

Permissions are assigned to Roles, and control data access throughout the platform. Learn more about Permissions.

The Permission Object ​

id uuid
Primary key of the permission rule.

role many-to-one
Role this permission applies to. Many-to-one to roles. null is used for public permissions.

collection string
Collection this permission rule applies to.

action string
What CRUD operation this permission rule applies to. One of create, read, update, delete.

permissions object
What rules the item must pass before the role is allowed to alter it. Follows the Filter Rules spec.

validation object
What rules the provided values must pass before the role is allowed to submit them for insertion/update. Follows the Filter Rules spec.

preset object
Additional default values for the role.

fields array
What fields the user is allowed to alter.

json
{
	"id": 34,
	"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
	"collection": "pages",
	"action": "create",
	"permissions": null,
	"validation": {
		"title": {
			"_contains": "Directus"
		}
	},
	"presets": {
		"published": false
	},
	"fields": ["title", "translations"]
}

List Permissions ​

List all permissions that exist in Directus.

Permissions

The data returned in this endpoint will be filtered based on the user's permissions. For example, permissions for a role other than the current user's role won't be returned.

Query Parameters ​

Supports all global query parameters.

Returns ​

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

REST API ​

GET /permissions
SEARCH /permissions

Learn more about SEARCH ->

GraphQL ​

POST /graphql/system
graphql
type Query {
	permissions: directus_permissions
}
Example ​
graphql
query {
	permissions {
		action
		role
		collection
	}
}

Retrieve a Permission ​

List an existing permission by primary key.

Query Parameters ​

Supports all global query parameters.

Returns ​

Returns the requested permission object.

REST API ​

GET /permissions/:id
Example ​
json
// GET /permissions/34

{
	"data": {
		"id": 34,
		"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"collection": "pages",
		"action": "create",
		"permissions": null,
		"validation": {
			"title": {
				"_contains": "Directus"
			}
		},
		"presets": {
			"published": false
		},
		"fields": ["title", "translations"]
	}
}

GraphQL ​

POST /graphql/system
graphql
type Query {
	permissions_by_id(id: ID!): directus_permissions
}
Example ​
graphql
query {
	permissions_by_id(id: 34) {
		role
		collection
		action
	}
}

Create a Permission Rule ​

Create a new permission rule

Query Parameters ​

Supports all global query parameters.

Request Body ​

A partial permissions object. action and collection are required.

Returns ​

Returns the permission object for the created permission.

REST API ​

POST /permissions
Example ​
json
// Request

{
	"collection": "pages",
	"action": "read",
	"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
	"fields": ["id", "title"]
}

GraphQL ​

POST /graphql/system
graphql
type Mutation {
	create_permissions_item(data: create_directus_permissions_input!): directus_permissions
}
Example ​
graphql
mutation {
	create_permissions_item(
		data: { collection: "pages", action: "read", role: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
	) {
		id
		collection
		action
	}
}

Create Multiple Permission Rules ​

Create multiple new permission rules

Query Parameters ​

Supports all global query parameters.

Request Body ​

An array of partial permissions objects. action and collection are required.

Returns ​

Returns the permission objects for the created permissions.

REST API ​

POST /permissions
Example ​
json
// Request

[
	{
		"collection": "pages",
		"action": "read",
		"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"fields": ["id", "title"]
	},
	{
		"collection": "pages",
		"action": "create",
		"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"fields": ["id", "title"]
	}
]

GraphQL ​

POST /graphql/system
graphql
type Mutation {
	create_permissions_items(data: [create_directus_permissions_input!]!): [directus_permissions]
}
Example ​
graphql
mutation {
	create_permissions_items(
		data: [
			{ collection: "pages", action: "read", role: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
			{ collection: "pages", action: "create", role: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
		]
	) {
		id
		collection
		action
	}
}

Update Permissions ​

Update an existing permissions rule.

Query Parameters ​

Supports all global query parameters.

Request Body ​

A partial permissions object.

Returns ​

Returns the permission object for the updated permission.

REST API ​

PATCH /permissions/:id
Example ​
json
// PATCH /permissions/34

{
	"fields": ["id", "title", "body"]
}

GraphQL ​

POST /graphql/system
graphql
type Mutation {
	update_permissions_item(id: ID!, data: update_directus_permissions_input!): directus_permissions
}
Example ​
graphql
mutation {
	update_permissions_item(id: 34, data: { fields: ["id", "title", "body"] }) {
		id
		action
		collection
	}
}

Update Multiple Permissions ​

Update multiple existing permissions rules.

Query Parameters ​

Supports all global query parameters.

Request Body ​

Request Body ​

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

data Required
Any of the permission object's properties.

Returns ​

Returns the permission object for the updated permissions.

REST API ​

PATCH /permissions
Example ​
json
// PATCH /permissions

{
	"keys": [34, 65],
	"data": {
		"fields": ["id", "title", "body"]
	}
}

GraphQL ​

POST /graphql/system
graphql
type Mutation {
	update_permissions_items(id: [ID!]!, data: update_directus_permissions_input!): [directus_permissions]
}
Example ​
graphql
mutation {
	update_permissions_items(ids: [34, 64], data: { fields: ["id", "title", "body"] }) {
		id
		action
		collection
	}
}

Delete Permissions ​

Delete an existing permissions rule

Returns ​

Empty body.

REST API ​

DELETE /permissions/:id
Example ​
DELETE /permissions/34

GraphQL ​

POST /graphql/system
graphql
type Mutation {
	delete_permissions_item(id: ID!): delete_one
}
Example ​
graphql
mutation {
	delete_permissions_item(id: 34) {
		id
	}
}

Delete Multiple Permissions ​

Delete multiple existing permissions rules

Request Body ​

An array of permission primary keys

Returns ​

Empty body.

REST API ​

DELETE /permissions
Example ​
json
// DELETE /permissions

[34, 64]

GraphQL ​

POST /graphql/system
graphql
type Mutation {
	delete_permissions_items(ids: [ID!]!): delete_many
}
Example ​
graphql
mutation {
	delete_permissions_items(ids: [34, 64]) {
		ids
	}
}