Directus Permissions: Roles, Policies and Access Control

Directus Permissions: Roles, Policies and Access Control

Directus permissions are built from three pieces: permissions (what one collection and action allows), policies (named groups of permissions) and roles (how people sit in your organization). Policies attach to roles or directly to users, and the access a user ends up with is the sum of everything attached. Get that model right and the rest is configuration. Get it wrong and you get the confusing behavior that fills the Directus issue tracker: an admin who “lacks permission,” a files rule that does nothing, a users collection that leaks fields.

This guide walks through the model, shows how to configure collection, field and item access, covers a draft-to-publish approval pattern, and ends with how to test and harden what you built. We build and maintain Directus projects at Ridiculous Engineering, so the advice leans toward what holds up in production.

Key Takeaways

• Every permission applies to one collection and one action, and it can allow everything, allow nothing, or apply custom rules.
• Policies bundle permissions and attach to roles or users. Effective access is additive, so a user gets the union of all their policies.
• Keep the Public role denied by default, and keep changes to users, roles, policies and permissions with trusted administrators only.
• Use item filters, field lists, validation and presets to express real business rules, such as “authors only edit their own drafts.”
• Check what a user can actually do through the Permissions API instead of guessing from the settings screen.

Table of Contents

• How the Directus permission model fits together
• Configuring access for collections, fields and items
• Filters, presets and validation: three tools, three jobs
• A worked example: draft, review, publish
• Public access and administrator access
• Testing and troubleshooting what users can actually do
• Common mistakes we see in real projects
• Planning permissions before you build
• Working with Ridiculous Engineering on Directus
• FAQ
• Sources

How the Directus permission model fits together

According to the Directus access control documentation, a permission applies to a single collection and action. For each one you choose full access, no access, or custom rules built on item filters, field lists, validation and presets.

The pieces stack like this:

• Permission: one collection, one action (create, read, update, delete, share), with its rules.
• Policy: a group of permissions. Policies can be applied to roles or to individual users.
• Role: a description of where a person sits in the organization. A role can have policies, users and child roles.
• User: a person or service account, who may hold a role, policies directly, or both.

Two behaviors matter most. First, effective permissions are additive: if one policy allows reading articles and another allows updating them, the user can do both. There is no “deny” that overrides an “allow” from another policy, so you remove access by removing the policy, not by stacking a restriction on top. Second, the Administrator role is unrestricted and the Public role governs requests made without authentication.

The practical consequence is that policies are the unit you should design around. Roles answer “who is this person?” Policies answer “what may be done?” Keeping those questions separate is what stops a permissions setup from turning into a pile of one-off exceptions. If you want the broader design thinking behind this, our role-based access control design blueprint covers how to derive roles from real job functions before you touch any tool.

Why the Administrator role behaves differently

Administrators cannot be given more or less access. The role is unrestricted by definition, so you cannot narrow it with rules. If you need someone who manages content but must not touch settings, build a separate policy for that person. Do not reach for an admin account and hope to constrain it. Many of the “permissions problems on root user” reports in the public issue tracker come from expecting admin accounts to be configurable like any other role.

Configuring access for collections, fields and items

For each collection and action you pick one of three settings: all, none or custom. Custom is where the work happens. Per the access control guide, custom permissions can define which items the action applies to and which fields are permitted.

Collection-level access

Start here and stay conservative. A typical content team policy might look like this:

This table is an illustration of a pattern, not a prescribed default. The point is the shape: reference data is read-only, content is created and edited under conditions, and nobody on the content team deletes anything.

Field-level access

Within a custom rule you list the fields a user may touch. Treat this as an allow-list. Anything you do not tick is invisible or immutable for that policy, which is exactly what you want for internal notes, pricing fields or workflow status flags.

One trap shows up repeatedly in public discussions: unticking every field on a system collection such as the users table and expecting the collection to disappear from view. If the goal is that users should not see other people’s details, restrict the items with a filter (see below) and then limit the fields, rather than relying on an empty field list alone.

Item-level access with filters

Item rules decide which rows an action can reach. Directus’s own React authentication guide shows two patterns worth copying:

1. Own-content authoring. Grant create access with a preset that sets the author field to $CURRENT_USER, then grant update and delete only where user_created equals $CURRENT_USER (Using Authentication in React).
2. Self-service profile. Give read and update item rules on directus_users restricted to id = $CURRENT_USER, so people can see and edit only their own record (same guide).

These two rules cover a surprising share of real applications: customer portals, contributor dashboards, partner extranets and internal tools where each person owns their own records.

Filters, presets and validation: three tools, three jobs

People confuse these constantly, so it helps to separate them.

• Item filter: decides which existing items the action can see or change. It answers “which rows?”
• Validation: checks the values being submitted. It answers “is this change allowed?”
• Preset: fills in defaults when an item is created. It answers “what should be pre-filled?”

The access control guide describes this division: filters define accessible items and validate submitted values, while presets set defaults. Once you hold the distinction, most permission puzzles become easy to place. “Authors should only edit their own posts” is a filter. “Authors may only save posts as draft” is validation. “New posts should record who wrote them” is a preset.

A worked example: draft, review, publish

Approval workflows are where Directus permissions earn their keep. The official tutorial on content approval workflows with custom permissions builds one with nothing but policies, and the structure is worth understanding.

Authors

• Create is allowed, with validation that permits only draft articles.
• Update is allowed on items that are drafts or under review.
• Update validation permits only a transition to “under review,” so an author cannot publish their own work.

Editors

• Update is allowed only on articles that are under review.
• Update validation requires the status change to be to “published.”
• Delete and share stay restricted.

The design principle is that each role can move an item exactly one step forward, and the filter ensures they only see items at the stage they own. Nothing in this requires code. It also means the workflow is enforced at the API, not just in the app’s interface, so a custom front end or a script cannot sidestep it.

If you are comparing how other teams structure due dates and draft handoffs around a flow like this, due-day draft workflows show a related editorial pattern. When approvals need notifications, escalations or system hooks on top of permissions, that is the territory of Flows, which we cover in Directus Flows in production.

Public access and administrator access

These two ends of the spectrum cause the most serious mistakes, so they deserve their own rules.

The Public role

Keep Public denied by default. Grant read access only to data that is genuinely meant for anyone on the internet, and narrow it twice: with an item filter (for example, only items with status published) and with a field list (leave out internal notes, author emails and anything else you would not print on a billboard). The Directus guidance is also explicit that sensitive and system collections should not be exposed without a reason.

A quick habit helps: whenever you add a Public permission, ask what a stranger with a script could pull if they requested every item in that collection. If the answer makes you uncomfortable, tighten the filter.

Administrators and the identity collections

Reserve changes to users, roles, policies, permissions, settings and the schema for trusted administrators. The Directus security best practices recommend administrator-only create, update and delete on directus_users, directus_roles and directus_policies, because those abilities can create accounts, assign privileges or change what a role can reach. Anyone who can edit these can grant themselves anything.

For ordinary users who need to edit their own profile, the same guidance recommends:

1. An item rule of id = $CURRENT_USER.
2. Removing role and policies from the editable fields, so a person cannot promote themselves.
3. No broader user-management access.

Step two is the one teams forget. A self-edit rule without field restrictions is a privilege escalation waiting to happen.

Testing and troubleshooting what users can actually do

The settings screen tells you what you configured. It does not tell you what a given user ends up with once several policies combine. For that, use the Permissions API described in the security best practices: it reports the current user’s access by collection and action as none, partial or full, and item-level checks can inspect a specific record.

A reliable testing routine:

1. Create a test user for each real role, not just an admin.
2. Authenticate as that user and call the permissions endpoint to see access by collection and action.
3. For every “partial” result, check a specific item that should be allowed and one that should not.
4. Re-run the check after every policy change, because additive access means a new policy can quietly widen what a user can do.

When access is wider than you expect

The cause is almost always additive stacking. A user holds a role with one policy and a directly attached policy with another, and the union is larger than anyone intended. List every policy that reaches the user, including those inherited through child roles, and remove the one that grants the extra access.

When access is narrower than you expect

Check these in order:

• Is the action set to custom with a filter that excludes the item? A status or ownership filter is the usual culprit.
• Is the field you need missing from the permitted field list?
• Does validation reject the submitted value? The failing change may be the specific value, not the action.
• For system collections such as files and users, did you set rules for the right action? Reports of files rules “not working as expected” are usually a missing read or update permission that the interface depends on, so test the exact requests your app makes.

Changes can also appear stale if you test with an old session. Re-authenticate before concluding a rule is broken.

Common mistakes we see in real projects

• One policy per person. It feels precise and becomes unmaintainable by the tenth hire. Build policies around job functions and attach them to roles.
• Giving admin to unblock someone. The temporary admin account becomes permanent. Write the narrower policy instead.
• Forgetting that access is additive. Teams try to “deny” by adding a restrictive policy. Remove the permissive one.
• Self-edit without field limits. Users can alter their own role or policies.
• Trusting the front end. Hiding a button is not access control. Rules belong in the permissions layer, where every client is subject to them.
• Never reviewing. Access drifts as people change jobs. Put a policy review on the calendar quarterly.

Planning permissions before you build

The cheapest time to get permissions right is before the schema is final, because collection design determines what filters you can write. Add an owner field where records belong to a person, a status field where records move through stages, and a clean split between public and internal content. Then write down, in plain language, who may create, read, update and delete each collection and under what conditions. Translating that table into policies takes an afternoon. Reverse-engineering it from a live system takes weeks.

If you are weighing whether Directus fits your project at all, our honest Directus review covers where it shines and where we would pick something else. And if you are scoping outside help, what to settle in a Directus consulting SOW lists the questions worth answering before you sign.

Working with Ridiculous Engineering on Directus

We design and build headless CMS platforms, including Directus implementations and migrations, with permission models designed around how your team actually works. For teams that want a managed option, Consus, our managed headless CMS, is offered through a focused beta and consultation process rather than as self-service software. Pricing for custom work is scoped on request. Tell us about your roles and approval flow, and we will tell you how we would model it.

FAQ

What is the difference between a role and a policy in Directus?

A role describes a person’s position in your organization and can hold users, policies and child roles. A policy is a group of permissions that can be attached to a role or directly to a user. Design access around policies and use roles to organize who receives them.

Can I deny access with a second policy?

No. Effective permissions are additive, so a user receives the union of everything their policies allow. To remove access, detach or edit the policy that grants it rather than adding a restrictive one.

How do I let users edit only their own content?

Grant create access with a preset that sets the author field to $CURRENT_USER, then limit update and delete to items where user_created equals $CURRENT_USER. Directus documents this pattern in its React authentication guide. For profile edits, restrict directus_users to id = $CURRENT_USER.

How should I configure the Public role?

Leave it denied by default and grant read access only to data meant for everyone. Narrow that access with item filters, such as published status only, and with a field list that leaves out internal data. Avoid exposing system collections.

How can I check what a user can really access?

Use the Permissions API while authenticated as that user. It reports none, partial or full access by collection and action, and item-level checks can inspect a specific record. Run it after each policy change.

Sources

• Access Control, Directus documentation
• Security Best Practices, Directus documentation
• Using Authentication in React, Directus documentation
• Build Content Approval Workflows with Custom Permissions, Directus documentation

Recommended

• Directus Consulting: SOW, Budget, and Timeline Before You Sign
• Directus Flows in Production: Architecture, Security, and Reliability
• Role-Based Access Control Design: A Practical Blueprint