60df20d780
* Simplified generics and imports for items page snippets * Simplified generics and imports for files page snippets * Fixing simplified generic snippets in items page * Simplified generics and imports for activity page snippets * Simplified generics and imports for collections page snippets * Simplified generics and imports for dashboards page snippets * Simplified generics and imports for extensions page snippets * Simplified generics and imports for fields page snippets * Simplified generics and imports for flows page snippets * Simplified generics and imports for folders page snippets * Simplified generics and imports for notifications page snippets * Simplified generics and imports for operations page snippets * Simplified generics and imports for panels page snippets * Simplified generics and imports for permissions page snippets * Simplified generics and imports for presets page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for revisions page snippets * Simplified generics and imports for roles page snippets * Consolidated imports for schema page snippets * Simplified generics and imports for server page snippets * Simplified generics and imports for settings page snippets * Fixed mixed up snippets and simplified generics and imports for shares page snippets * Simplified generics and imports for translation page snippets * Fixed mixed up snippets and simplified generics and imports for user page snippets * Simplified generics and imports fo uutilitie pages snippets * Simplified generics and imports for webhook pages snippets * Simplified generics and imports for authentication pages snippets * Consolidated imports for query pages sdk snippets * Format files * Update lockfile * Fix spelling * Format snippets * Aling `result` const * Small clean-ups - Align `SEARCH` snippets, move "Learn more..." next to other hint - ids -> IDs - Other alignments --------- Co-authored-by: Bevis Halsey-Perry <hi@be7.is> Co-authored-by: Pascal Jufer <pascal-jufer@bluewin.ch>
15 KiB
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.
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']));