Access Control

Access control is a critical part of managing data - what different users in their various roles should be able to create, read, update, delete, and share.

You can find Access Control in the Settings module.

Users

A user is an item in the directus_users collection and typically referring to a person, application, or service that needs access to a Directus project.

Permissions

A permission is set on a collection and an action. The available actions in Directus are create, read, update, delete, and share. Permissions can provide all access, no access, or use custom permissions.

Custom Permissions

Custom permissions provide more granularity than 'all' or 'none'. They impact what items and fields a user can access, and have permission-level validation and presets.

Item Permissions

Use filter rules to define which items in a collection a user can access.

Field Permissions

Define which fields the role is included in this permission. As a permission is scoped to both a collection and an action, a different set of fields can be provided to each action.

Field Validation

Use filter rules to validate field values when an item is created or updated.

Field Presets

Define default field values when an item is created or updated. The value will appear in Editor, and can later be updated.

Policies are a group of permissions that can be applied to users or roles.

As a user starts with no permissions, and multiple policies can set a permission on the same collection and actions. Applying policies is additive - each policy can add to existing permissions, but not take them away.

Roles

Roles are an organizational tool that define a user's position within a project. A role can have any number of policies attributed to it, and be applied to any number of users. Roles can also have any number of policies and child roles.

Administrator Role

An administrator role provides complete, unrestricted control over the project, including the data model and all data. This cannot be limited, as by definition it would no longer be an administrator role. You need at least one user in an administrator role.

Public Role

A public role defines access permissions for unauthenticated requests to the database. That means that if you enable an access permission for this role, everybody has that permission enabled. All public permissions are off by default. It is up to the administrators to re-configure these and define exactly what the public role has access to.

Statuses

A policy can toggle access to the App (Data Studio). If you only want a user to access the project via API, leave this disabled.

An admin can set the user status. Only the active state is able to authenticate, with all others being descriptive inactive states.

• Draft: an incomplete user item.
• Invited: has a pending invite to the Directus project.
• Unverified: registered but has not yet verified their email address.
• Active: access to the Directus project via API or the Data Studio.
• Suspended: a User that has been temporarily disabled.
• Archived: a soft-deleted user.

Limiting to Specific IP Addresses

A policy can also have a specific allowlist of IP addresses, IP ranges, and CIDR blocks which allow access. Leave this empty to allow all IP addresses.

IP access is configured at the individual policy level, meaning each policy maintains its own independent set of IP restrictions. This granular approach provides several advantages:

• Each policy's IP allowlist operates independently without affecting other policies in your system.
• Different resources often require different levels of network security. Combining multiple policies with varying IP access can expand permissions depending on what IP the user is connecting from.

Studio Users

Studio Users in Directus are used in the context of licensing and billing for Directus Cloud. A studio user meets at least one of the following criteria:

1. At least one policy with 'Admin Access' enabled.
2. At least one policy with 'App Access' enabled, allowing access to the Data Studio.

Combining Multiple Policies

When multiple policies are assigned to a role or user, the system evaluates and combines these policies depending on the type of restriction or permission being applied. Understanding how these rules combine is essential for designing effective access control strategies.

Field Permissions: Additive

Field permissions for the same collection follow an additive model. This means that permissions from multiple applicable policies are merged together to create a comprehensive list of accessible fields.

How It Works: After IP restrictions have filtered our relevant policies, the system combines field permissions from all remaining active policies. If multiple policies grant access to different fields within the same collection, the user receives access to the union of all specified fields.

Practical Example: Consider two active policies for the Users collection:

Policy A: Grants access to fields ["name", "email", "created_at"]
Policy B: Grants access to fields ["email", "role", "last_login"]

The combined field permissions from these two policies would be ["name", "email", "created_at", "role", "last_login"], giving the user access to all five fields. Duplicate fields (like "email" in this example) are automatically deduplicated.

Permission Expansion: This additive approach means that additional policies can only expand field access, never restrict it. Once a field is granted by any active policy, it remains accessible unless explicitly blocked by item-level permissions.

Item Rules: Additive

Item rules (row-level security rules) also follow an additive model, where filtering conditions from multiple policies are merged using logical OR operations for the same collection.

How It Works: Item rules from all active policies targeting the same collection are combined, allowing access to records that match any of the specified conditions. This creates a union of accessible items across all policies.

Practical Example: Two active policies with item rules for the Orders collection:

Policy A: user_id = $CURRENT_USER.id - user can see their own orders
Policy B: department = $CURRENT_USER.department AND status = 'public' - user can see public orders from their department

The combined rule becomes: (user_id = current_user.id) OR (department = current_user.department AND status = 'public') Users can access orders that match either condition.

Complex Rule Merging: When policies contain multiple collections or complex nested conditions, the system maintains the logical integrity of each policy's rules while combining them at the collection level. This ensures that the original intent of each policy is preserved while maximizing user access.

IP Access: Subtractive

IP access restrictions follow a subtractive model, meaning that if a user's IP address doesn't match the allowlist, that entire policy is removed from the evaluation chain.

How It Works: When a request arrives, the system first checks the requesting IP address against each policy's IP allowlist. Any policy whose IP restrictions are not satisfied is immediately excluded from further evaluation. Only policies that pass the IP access check remain active for that request.

Practical Example: Consider a user assigned three policies:

Policy A: Allows IPs 192.168.1.0/24, grants read access to Users collection
Policy B: Allows IPs 10.0.0.0/8, grants write access to Orders collection
Policy C: No IP restrictions, grants read access to Products collection

If a request comes from IP 192.168.1.100, only Policy A and Policy C remain active. Policy B is completely removed from consideration because the IP doesn't match its allowlist, even though it might grant valuable permissions.

Strategic Considerations: This subtractive behavior means you should carefully design IP restrictions to avoid accidentally blocking legitimate access. Consider using broader IP ranges in policies that grant essential permissions, or create separate policies without IP restrictions for critical baseline access.