Permissions

Permissions are assigned to Policies, and control data access throughout the platform. [Learn more about permissions](/auth/access-control).

List Permission Rules

List all permission rules that exist in Directus.

Query Parameters

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

offset

integer

How many items to skip when fetching data.

meta

string

What metadata to return in the response.

sort

array

How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

page

integer

Cursor for use in pagination. Often used in combination with limit.

Response

Successful request

data

array

meta

object

GET /permissions

Response Example

{
  "data": [
    {
      "id": 1,
      "collection": "customers",
      "action": "create",
      "permissions": {},
      "validation": {},
      "presets": {},
      "fields": []
    }
  ],
  "meta": {}
}

Create Multiple Permission Rules

Create multiple new permission rules.

Query Parameters

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

offset

integer

How many items to skip when fetching data.

meta

string

What metadata to return in the response.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

page

integer

Cursor for use in pagination. Often used in combination with limit.

Request Body

data

array

Response

Successful request

data

array

meta

object

POST /permissions

Response Example

{
  "data": [
    {
      "id": 1,
      "collection": "customers",
      "action": "create",
      "permissions": {},
      "validation": {},
      "presets": {},
      "fields": []
    }
  ],
  "meta": {}
}

Delete Multiple Permission Rules

Delete multiple existing permission rules.

Query Parameters

Request Body

An array of permissions primary keys.

[array]

array

DELETE /permissions

Update Multiple Permission Rules

Update multiple permissions at the same time.

Query Parameters

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

meta

string

What metadata to return in the response.

offset

integer

How many items to skip when fetching data.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

Request Body

data

object

keys

array

Response

Successful request

data

array

meta

object

PATCH /permissions

Response Example

{
  "data": [
    {
      "id": 1,
      "collection": "customers",
      "action": "create",
      "permissions": {},
      "validation": {},
      "presets": {},
      "fields": []
    }
  ],
  "meta": {}
}

Create a Permission Rule

Create a new permission rule.

Query Parameters

meta

string

What metadata to return in the response.

Request Body

collection

string

What collection this permission applies to.

comment

string

If the user can post comments.

create

string

If the user can create items.

delete

string

If the user can update items.

explain

string

If the user is required to leave a comment explaining what was changed.

read

string

If the user can read items.

role

integer

Unique identifier of the role this permission applies to.

read_field_blacklist

array

Explicitly denies read access for specific fields.

status

string

What status this permission applies to.

status_blacklist

array

Explicitly denies specific statuses to be used.

update

string

If the user can update items.

write_field_blacklist

array

Explicitly denies write access for specific fields.

Response

Successful request

data

object

POST /permissions‎

Response Example

{
  "data": {
    "id": 1,
    "collection": "customers",
    "action": "create",
    "permissions": {},
    "validation": {},
    "presets": {},
    "fields": []
  }
}

Retrieve a Permission Rule

Retrieve a single permission rules object by unique identifier.

Query Parameters

integer

Identifier for the object.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Response

Successful request

data

object

GET /permissions/{id}

Response Example

{
  "data": {
    "id": 1,
    "collection": "customers",
    "action": "create",
    "permissions": {},
    "validation": {},
    "presets": {},
    "fields": []
  }
}

Delete a Permission Rule

Delete an existing permission rule.

Query Parameters

integer

Identifier for the object.

DELETE /permissions/{id}

Update a Permission Rule

Update an existing permission rule.

Query Parameters

integer

Identifier for the object.

meta

string

What metadata to return in the response.

Request Body

collection

object

What collection this permission applies to.

comment

string

If the user can post comments. full.

create

string

If the user can create items.

delete

string

If the user can update items.

explain

string

If the user is required to leave a comment explaining what was changed.

read

string

If the user can read items.

read_field_blacklist

object

Explicitly denies read access for specific fields.

role

object

Unique identifier of the role this permission applies to.

status

object

What status this permission applies to.

status_blacklist

object

Explicitly denies specific statuses to be used.

update

string

If the user can update items.

write_field_blacklist

object

Explicitly denies write access for specific fields.

Response

Successful request

data

object

PATCH /permissions/{id}

Response Example

{
  "data": {
    "id": 1,
    "collection": "customers",
    "action": "create",
    "permissions": {},
    "validation": {},
    "presets": {},
    "fields": []
  }
}

Get Current User Permissions

Check the current user's permissions across all collections. The response is an object that contains one entry for every collection with at least one permission. Each collection has entries corresponding to the actions the user is able to perform on the collection. The `access` property indicates the level of access the user has for an action for a collection. `"none"` means the user has no access, `"partial"` means the user has access to some items, but may not have access to all items, and `"full"` means the user has access to all items.

Query Parameters

GET /permissions/me

Check Permissions for a Specific Item

Check the current user's permissions on a specific item. For a singleton where update access is given, the presets and fields properties from the corresponding update permission are additionally returned. 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.

Query Parameters

collection

string

Collection of which you want to retrieve the items from.

integer

Identifier for the object.

GET /permissions/me/{collection}/{id}