mirror of
https://github.com/directus/directus.git
synced 2026-01-29 03:48:01 -05:00
540 lines
7.9 KiB
Markdown
540 lines
7.9 KiB
Markdown
---
|
|
description: REST and GraphQL API documentation on the Permissions collection in Directus.
|
|
readTime: 5 min read
|
|
pageClass: page-reference
|
|
---
|
|
|
|
# Permissions
|
|
|
|
> Permissions are assigned to Roles, and control data access throughout the platform.
|
|
> [Learn more about Permissions](/getting-started/glossary#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](/reference/system/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](/reference/filter-rules).
|
|
|
|
`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](/reference/filter-rules).
|
|
|
|
`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.
|
|
|
|
::: 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.
|
|
|
|
:::
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/query).
|
|
|
|
### Returns
|
|
|
|
An array of up to [limit](/reference/query#limit) [permission objects](#the-permission-object). If no items are
|
|
available, data will be an empty array.
|
|
|
|
### REST API
|
|
|
|
```
|
|
GET /permissions
|
|
SEARCH /permissions
|
|
```
|
|
|
|
[Learn more about SEARCH ->](/reference/introduction#search-http-method)
|
|
|
|
### 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](/reference/query).
|
|
|
|
### Returns
|
|
|
|
Returns the requested [permission object](#the-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](/reference/query).
|
|
|
|
### Request Body
|
|
|
|
A partial [permissions object](#the-permission-object). `action` and `collection` are required.
|
|
|
|
### Returns
|
|
|
|
Returns the [permission object](#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](/reference/query).
|
|
|
|
### Request Body
|
|
|
|
An array of partial [permissions objects](#the-permission-object). `action` and `collection` are required.
|
|
|
|
### Returns
|
|
|
|
Returns the [permission objects](#the-permission-object) 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](/reference/query).
|
|
|
|
### Request Body
|
|
|
|
A partial [permissions object](#the-permission-object).
|
|
|
|
### Returns
|
|
|
|
Returns the [permission object](#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](/reference/query).
|
|
|
|
### 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](#the-permission-object)'s properties.
|
|
|
|
### Returns
|
|
|
|
Returns the [permission object](#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
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|