13e47efe80
* Removed RC remtions * Format policies --------- Co-authored-by: Rijk van Zanten <rijkvanzanten@me.com>
20 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 Policies, and control data access throughout the platform. Learn more about Permissions.
The Permission Object
id uuid
Primary key of the permission rule.
policy many-to-one
Policy this permission applies to. Many-to-one to policies.
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 custom permission rules the item must pass before users with the policy are allowed to operate on it. Follows the Filter Rules spec.
validation object
What rules the provided values must pass before users with the policy are allowed to submit them for insertion/update. Follows
the Filter Rules spec.
presets object
Additional default values for the item that are applied by users with the policy.
fields array
What fields the user is allowed to alter.
{
"id": 34,
"policy": "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.
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
policy
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) {
policy
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",
"policy": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
"fields": ["id", "title"]
}
POST /graphql/system
mutation {
create_permissions_item(
data: { collection: "pages", action: "read", policy: "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({
policy: '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",
"policy": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
"fields": ["id", "title"]
},
{
"collection": "pages",
"action": "create",
"policy": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
"fields": ["id", "title"]
}
]
POST /graphql/system
mutation {
create_permissions_items(
data: [
{ collection: "pages", action: "read", policy: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
{ collection: "pages", action: "create", policy: "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([
{
policy: '39a178f6-d4d6-40e1-b0e7-ec6daaac8747',
collection: 'articles',
action: 'delete',
fields: ['*'],
},
{
policy: '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']));
Get Current User Permissions
Check the current user's permissions across all collections.
Request
GET /permissions/me
query {
permissions_me
}
import { createDirectus, rest, readUserPermissions } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
const result = await client.request(readUserPermissions());
Response
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.
{
"data": {
"<collection>": {
"create": {
"access": "none" | "partial" | "full",
"fields": permission_fields,
"presets": permission_presets
},
"read": {
"access": "none" | "partial" | "full",
"full_access": boolean,
"fields": permission_fields,
},
"update": {
"access": "none" | "partial" | "full",
"full_access": boolean,
"fields": permission_fields,
"presets": permission_presets
},
"delete": {
"access": "none" | "partial" | "full",
"full_access": boolean
},
"share": {
"access": "none" | "partial" | "full",
"full_access": boolean
}
}
}
}
Example
GET /permissions/me
{
"data": {
"articles": {
"create": {
"access": "full",
"fields": [
"*"
],
"presets": {
"title": "New Article"
}
},
"read": {
"access": "partial",
"fields": [
"*"
]
},
"update": {
"access": "full",
"fields": [
"*"
],
"presets": {}
},
"delete": {
"access": "full"
},
"share": {
"access": "none"
}
}
}
}
N/A
import { createDirectus, rest, readUserPermissions } from '@directus/sdk';
const client = createDirectus('https://directus.example.com').with(rest());
// collection item
const result = await client.request(readUserPermissions());
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'));