# 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.
{
"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.
# 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
// 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
type Query {
permissions_by_id(id: ID!): directus_permissions
}
# Example
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
// Request
{
"collection": "pages",
"action": "read",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
"fields": ["id", "title"]
}
# GraphQL
POST /graphql/system
type Mutation {
create_permissions_item(data: create_directus_permissions_input!): directus_permissions
}
# Example
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
// 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
type Mutation {
create_permissions_items(data: [create_directus_permissions_input!]!): [directus_permissions]
}
# Example
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
// PATCH /permissions/34
{
"fields": ["id", "title", "body"]
}
# GraphQL
POST /graphql/system
type Mutation {
update_permissions_item(id: ID!, data: update_directus_permissions_input!): directus_permissions
}
# Example
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
// PATCH /permissions
{
"keys": [34, 65],
"data": {
"fields": ["id", "title", "body"]
}
}
# GraphQL
POST /graphql/system
type Mutation {
update_permissions_items(id: [ID!]!, data: update_directus_permissions_input!): [directus_permissions]
}
# Example
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.
# Delete Multiple Permissions
Delete multiple existing permissions rules
← Notifications Presets →