directus/docs/reference/system/permissions.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Permissions collection in Directus.	5 min read	page-reference

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.

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

::: tip 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

GET /permissions

SEARCH /permissions

If using SEARCH you can provide a query object as the body of your request.

Learn more about SEARCH ->

POST /graphql/system

type Query {
	permissions: directus_permissions
}

import { createDirectus, rest, readPermissions } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readPermissions(query_object));

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

GET /permissions

SEARCH /permissions

POST /graphql/system

query {
	permissions {
		action
		role
		collection
	}
}

import { createDirectus, rest, readPermissions } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readPermissions({
		fields: ['*'],
	})
);

Retrieve a Permission

List an existing permission by primary key.

Request

GET /permissions/:id

POST /graphql/system

type Query {
	permissions_by_id(id: ID!): directus_permissions
}

import { createDirectus, rest, readPermission } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readPermission(permission_id, query_object));

Query Parameters

Supports all global query parameters.

Response

Returns the requested permission object.

Example

GET /permissions/34

POST /graphql/system

query {
	permissions_by_id(id: 34) {
		role
		collection
		action
	}
}

import { createDirectus, rest, readPermission } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readPermission('41', {
		fields: ['*'],
	})
);

Create a Permission Rule

Create a new permission rule

Request

POST /permissions

Provide a permission object as the body of your request.

POST /graphql/system

type Mutation {
	create_permissions_item(data: create_directus_permissions_input!): directus_permissions
}

import { createDirectus, rest, createPermission } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createPermission(permission_object));

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

POST /permissions

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

POST /graphql/system

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

import { createDirectus, rest, createPermission } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createPermission({
		role: '39a178f6-d4d6-40e1-b0e7-ec6daaac8747',
		collection: 'articles',
		action: 'delete',
		fields: ['*'],
	})
);

Create Multiple Permission Rules

Create multiple new permission rules

Request

POST /permissions

Provide an array of permission objects as the body of your request.

POST /graphql/system

type Mutation {
	create_permissions_items(data: [create_directus_permissions_input!]!): [directus_permissions]
}

import { createDirectus, rest, createPermissions } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createPermissions(permission_object_array));

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

POST /permissions

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

POST /graphql/system

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

import { createDirectus, rest, createPermissions } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createPermissions([
		{
			role: '39a178f6-d4d6-40e1-b0e7-ec6daaac8747',
			collection: 'articles',
			action: 'delete',
			fields: ['*'],
		},
		{
			role: '39a178f6-d4d6-40e1-b0e7-ec6daaac8747',
			collection: 'articles',
			action: 'update',
			fields: ['*'],
		},
	])
);

Update Permissions

Update an existing permissions rule.

Request

PATCH /permissions/:id

Provide a partial permissions object as the body of your request.

POST /graphql/system

type Mutation {
	update_permissions_item(id: ID!, data: update_directus_permissions_input!): directus_permissions
}

import { createDirectus, rest, updatePermission } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(updatePermission(permission_id, partial_permission_object));

Query Parameters

Supports all global query parameters.

Request Body

A partial permissions object.

Response

Returns the permission object for the updated permission.

Example

PATCH /permissions/34

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

mutation {
	update_permissions_item(id: 34, data: { fields: ["id", "title", "body"] }) {
		id
		action
		collection
	}
}

import { createDirectus, rest, updatePermission } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updatePermission('57', {
		fields: ['title', 'body'],
	})
);

Update Multiple Permissions

Update multiple existing permissions rules.

Request

PATCH /permissions

{
	"keys": permission_id_array,
	"data": partial_permission_object
}

POST /graphql/system

type Mutation {
	update_permissions_items(id: [ID!]!, data: update_directus_permissions_input!): [directus_permissions]
}

import { createDirectus, rest, updatePermissions } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(updatePermissions(permission_id_array, permission_object_panel));

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

PATCH /permissions

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

mutation {
	update_permissions_items(ids: [34, 64], data: { fields: ["id", "title", "body"] }) {
		id
		action
		collection
	}
}

import { createDirectus, rest, updatePermissions } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updatePermissions(['56', '57'], {
		fields: ['title', 'body'],
	})
);

Delete Permissions

Delete an existing permissions rule

Request

DELETE /permissions/:id

POST /graphql/system

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

import { createDirectus, rest, deletePermission } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deletePermission(permission_id));

Response

Empty body.

Example

DELETE /permissions/34

POST /graphql/system

mutation {
	delete_permissions_item(id: 34) {
		id
	}
}

import { createDirectus, rest, deletePermission } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deletePermissions('56'));

Delete Multiple Permissions

Delete multiple existing permissions rules

Request

DELETE /permissions

Provide an array of permissions IDs as the body of your request.

POST /graphql/system

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

import { createDirectus, rest, deletePermissions } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deletePermissions(permission_id_array));

Request Body

An array of permission primary keys

Response

Empty body.

Example

DELETE /permissions

[34, 64]

mutation {
	delete_permissions_items(ids: [34, 64]) {
		ids
	}
}

import { createDirectus, rest, deletePermissions } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deletePermissions(['56', '57']));

Check Permissions for a Specific Item

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

Request

GET /permissions/me/:collection/:id?

N/A

import { createDirectus, rest, readItemPermissions } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

// collection item
const result = await client.request(readItemPermissions(collection_name, item_id));

// singleton
const result = await client.request(readItemPermissions(collection_name));

Response

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

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

::: tip 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

GET /permissions/me/articles/15

{
	"data": {
		"update": {
			"access": true
		},
		"delete": {
			"access": false
		},
		"share": {
			"access": false
		}
	}
}

GET /permissions/me/about

{
	"data": {
		"update": {
			"access": true,
			"presets": {},
			"fields": ["*"]
		},
		"delete": {
			"access": false
		},
		"share": {
			"access": false
		}
	}
}

N/A

import { createDirectus, rest, readItemPermissions } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

// collection item
const result = await client.request(readItemPermissions('articles', '15'));

// singleton
const result = await client.request(readItemPermissions('about'));