Skip to content
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.

presets 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"]
}
{
	"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.

Request

Query Parameters

Supports all global query parameters.

Response

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

Example

Retrieve a Permission

List an existing permission by primary key.

Request

Query Parameters

Supports all global query parameters.

Response

Returns the requested permission object.

Example

Create a Permission Rule

Create a new permission rule

Request

Query Parameters

Supports all global query parameters.

Request Body

A partial permissions object. action and collection are required.

Response

Returns the permission object for the created permission.

Example

Create Multiple Permission Rules

Create multiple new permission rules

Request

Query Parameters

Supports all global query parameters.

Request Body

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

Response

Returns the permission objects for the created permissions.

Example

Update Permissions

Update an existing permissions rule.

Request

Query Parameters

Supports all global query parameters.

Request Body

A partial permissions object.

Response

Returns the permission object for the updated permission.

Example

Update Multiple Permissions

Update multiple existing permissions rules.

Request

Query Parameters

Supports all global query parameters.

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.

Example

Delete Permissions

Delete an existing permissions rule

Request

Response

Empty body.

Example

Delete Multiple Permissions

Delete multiple existing permissions rules

Request

Request Body

An array of permission primary keys

Response

Empty body.

Example

Check Permissions for a Specific Item

Check the current user's permissions on a specific item.

Request

Response

json
{
	"data": {
		"update": {
			"access": boolean
		},
		"delete": {
			"access": boolean
		},
		"share": {
			"access": boolean
		}
	}
}
{
	"data": {
		"update": {
			"access": boolean
		},
		"delete": {
			"access": boolean
		},
		"share": {
			"access": boolean
		}
	}
}

For a Singleton where update access is given, the presets and fields properties from the corresponding update permission are additionally returned:

json
{
	"data": {
		"update": {
			"access": true,
			"presets": permission_presets,
			"fields": permission_fields
		},
		"delete": {
			"access": boolean
		},
		"share": {
			"access": boolean
		}
	}
}
{
	"data": {
		"update": {
			"access": true,
			"presets": permission_presets,
			"fields": permission_fields
		},
		"delete": {
			"access": boolean
		},
		"share": {
			"access": boolean
		}
	}
}

Non-existing Collection / Item

The response structure is maintained in any case, even if the collection or item does not exist. To check for the existence of an item, use the Get Items endpoint instead.

Example