Docyrus ACL Design
Configure tenant access control with docyrus acl, then validate the setup before handing it off. The Docyrus ACL system has five concepts:
| Concept |
What it is |
| Role |
Named permission group assigned to users |
| Hierarchy Unit |
Org-tree node for org-chart-aware row-level security (RLS) |
| Role Query |
Row-level filter attached to one or more roles for a data source |
| Operation |
System-defined permission slug (read-only — you can't create these) |
| Rule |
Binds a role to a target (data source / app / AI tool / settings) with a list of allowed operation slugs |
For platform concepts see the docyrus-platform skill. For CLI flag tables see the docyrus-cli-app skill. This skill is the ACL-specific workflow.
Workflow
Follow in order. A role without rules grants nothing useful.
Confirm auth.
docyrus auth who --json # confirm session + tenant
No session → stop and ask the user to run docyrus auth login.
Survey available operations. Before creating rules, know which operations exist per target type:
docyrus acl operations list --targetType data_source --json
docyrus acl operations list --targetType settings --json
docyrus acl operations list --targetType devtools --json
The full catalog is in references/operation-catalog.md.
Create roles. See Roles. One role per logical access level (e.g. "Viewer", "Editor", "Admin"). If the role is app-scoped pass --tenantAppId.
Create hierarchy units (skip if org-chart RLS is not needed). See Hierarchy Units. Build parent units before children.
Create role queries (skip if row-level record filtering is not needed). See Role Queries. Each role query narrows which records a role can see in a specific data source.
Create rules. Each rule grants a role a set of operations on one specific target. See Rules. Start with data_source rules, then settings, devtools, app, ai_tool as needed.
Validate. Re-read each object to confirm it landed with the right values. See Validate.
A full worked example (two-role CRM setup with data-source rules, a settings rule, and a role query) is in references/workflow-examples.md.
Roles
# List roles (optionally filter by name/slug)
docyrus acl roles list --json
docyrus acl roles list --search "editor" --json
# Get one role
docyrus acl roles get --roleId <uuid> --json
# Create a role
docyrus acl roles create --slug "crm-viewer" --name "CRM Viewer" --json
docyrus acl roles create --slug "crm-editor" --name "CRM Editor" \
--tenantAppId <app-uuid> --ownership CUSTOM --json
# Update a role (PATCH — any subset of fields)
docyrus acl roles update --roleId <uuid> --name "CRM Viewer (Read-Only)" --json
# Delete a role and all its assignments
docyrus acl roles delete --roleId <uuid> --json
Key fields:
--slug and --name are required on create.
--ownership ∈ SYSTEM | CUSTOM | APP | USER | PRODUCT (default CUSTOM).
--tenantAppId scopes the role to a specific app.
--disableLogin (int 0/1) prevents login when the user only holds this role.
--activitySummaryReportQueryId points to a custom query UUID for the role's activity summary dashboard.
--data '<json>' / --from-file ./payload.json override individual flags.
Hierarchy Units
Hierarchy units form an org-chart tree. Users are then assigned to units, and data-source data_access/unit_peer_access rules use that tree for RLS.
# List units (optionally filter by parent or name)
docyrus acl hierarchy-units list --json
docyrus acl hierarchy-units list --parentId <uuid> --json
docyrus acl hierarchy-units list --search "sales" --json
# Get one unit
docyrus acl hierarchy-units get --unitId <uuid> --json
# Create (build parents before children)
docyrus acl hierarchy-units create --name "Sales" --json
docyrus acl hierarchy-units create --name "Sales East" --parentId <sales-unit-uuid> --json
# Update
docyrus acl hierarchy-units update --unitId <uuid> --name "Sales West" --json
# Delete (fails if the unit has children — delete children first)
docyrus acl hierarchy-units delete --unitId <uuid> --json
--name is required on create.
--parentId is optional; omit for a root unit.
Role Queries
A role query is a DSQL-style filter object attached to one or more roles for a specific data source. Users whose active role matches are restricted to only the rows that match the query.
# List role queries
docyrus acl role-queries list --json
docyrus acl role-queries list --dataSourceId <uuid> --json
docyrus acl role-queries list --roleId <uuid> --json
docyrus acl role-queries list --restrictionLevel hidden --json
# Get one
docyrus acl role-queries get --roleQueryId <uuid> --json
# Create
docyrus acl role-queries create \
--roleIds "<role-uuid-1>,<role-uuid-2>" \
--dataSourceId <ds-uuid> \
--query '{"field":"status","operator":"eq","value":"active"}' \
--restrictionLevel "read-only" \
--json
# Update
docyrus acl role-queries update --roleQueryId <uuid> \
--query '{"field":"status","operator":"in","value":["active","pending"]}' --json
# Delete
docyrus acl role-queries delete --roleQueryId <uuid> --json
Key fields:
--roleIds comma-separated UUIDs — required on create.
--query JSON string of the filter object — required on create.
--dataSourceId scopes the query to one data source (optional — omit for a global filter).
--restrictionLevel ∈ hidden | read-only | not-deletable.
--filterChildRelations boolean — also apply the filter to child-relation queries.
Operations
Operations are system-defined and read-only — you can list them but cannot create, modify, or delete them.
# List all operations
docyrus acl operations list --json
# Filter by target type
docyrus acl operations list --targetType data_source --json
docyrus acl operations list --targetType settings --json
docyrus acl operations list --targetType devtools --json
docyrus acl operations list --targetType ai --json
docyrus acl operations list --targetType ai_tool --json
docyrus acl operations list --targetType field --json
# Search by name or slug
docyrus acl operations list --search "delete" --json
docyrus acl operations list --search "manage" --targetType settings --json
--targetType values: data_source, field, ai, settings, devtools, app, ai_tool.
The full operation catalog (slugs + names per target type) is in references/operation-catalog.md.
Rules
A rule grants a role a set of operations on exactly one target. One rule = one (role × target) binding.
# List rules
docyrus acl rules list --json
docyrus acl rules list --roleId <uuid> --json
docyrus acl rules list --targetType settings --json
docyrus acl rules list --dataSourceId <uuid> --json
docyrus acl rules list --appId <uuid> --json
docyrus acl rules list --aiToolId <uuid> --json
docyrus acl rules list --includeArchived --json # default: archived rules are hidden
# Get one rule
docyrus acl rules get --ruleId <uuid> --json
# Create a rule
# data_source target (default)
docyrus acl rules create \
--roleId <role-uuid> --dataSourceId <ds-uuid> \
--allowedOperations "view,create,edit,delete" --json
# settings target (no FK — omit dataSourceId/appId/aiToolId)
docyrus acl rules create \
--roleId <role-uuid> --targetType settings \
--allowedOperations "manage_users,manage_teams" --json
# devtools target
docyrus acl rules create \
--roleId <role-uuid> --targetType devtools \
--allowedOperations "cody,studio" --json
# ai_tool target
docyrus acl rules create \
--roleId <role-uuid> --targetType ai_tool --aiToolId <tool-uuid> \
--allowedOperations "allow" --json
# Update a rule (PATCH — supply only what changes)
docyrus acl rules update --ruleId <uuid> \
--allowedOperations "view,create,edit,delete,export" --json
# Archive a rule (soft disable — still visible with --includeArchived)
docyrus acl rules update --ruleId <uuid> --archived true --json
# Restore an archived rule
docyrus acl rules update --ruleId <uuid> --archived false --json
# Hard-delete a rule
docyrus acl rules delete --ruleId <uuid> --json
Key fields:
--roleId is required on create.
--targetType defaults to data_source; valid values: data_source, field, ai, settings, devtools, app, ai_tool.
--allowedOperations comma-separated list of operation slugs; must match real slugs for the target type.
- FK fields are mutually exclusive per rule row: set
--dataSourceId for data_source targets, --appId for app targets, --aiToolId for ai_tool targets. Leave all three null for settings, devtools, ai, field targets.
Critical rules
- All payload keys are camelCase.
--roleId, --dataSourceId, --allowedOperations, --roleIds, --targetType — never snake_case. The backend ACL DTOs are camelCase and GlobalValidationPipe does NOT transform snake_case → camelCase.
- One rule per (role × target FK). A unique database constraint prevents two rules for the same
(tenant, role, dataSource), (tenant, role, app), or (tenant, role, aiTool). Attempting to create a duplicate returns a 500 constraint error. Check with rules list --roleId <id> first.
targetType defaults to data_source on rules create — always pass it explicitly when creating non-data-source rules to avoid accidentally creating a data_source rule with null FK.
--allowedOperations is comma-separated on the CLI — it becomes a string[] in the request. Spaces around commas are stripped.
--roleIds is comma-separated for role queries (same pattern).
--query must be a JSON string for role queries — wrap in single quotes: --query '{"field":"owner","operator":"eq","value":"{{userId}}"}'.
- Operations are read-only. You cannot create or modify
core_acl_operation rows — only a superadmin can. Use acl operations list to discover slugs; pass them into --allowedOperations.
- Hierarchy unit delete rejects units with children. Delete leaves first, then parents.
- Archive ≠ delete.
rules update --archived true soft-disables a rule (the row stays and is hidden from normal list results). rules delete hard-removes it. Prefer archive when you may want to restore later.
--targetType uses underscores (data_source, ai_tool), not hyphens.
--restrictionLevel for role queries uses hyphens (read-only, not-deletable), not underscores.
- Validate then test. After configuring roles + rules, log in as a user with that role and confirm the access behaves as expected.
Validate
After authoring, confirm each object landed correctly:
Roles:
docyrus acl roles list --json # count matches
docyrus acl roles get --roleId <id> --json # slug, name, ownership, tenantAppId
Hierarchy units:
docyrus acl hierarchy-units list --json # tree structure
docyrus acl hierarchy-units list --parentId <id> --json # children of a node
Role queries:
docyrus acl role-queries list --roleId <id> --json # confirm query + restrictionLevel
Rules:
docyrus acl rules list --roleId <id> --json # all rules for the role
docyrus acl rules get --ruleId <id> --json # confirm allowedOperations, targetType, FK
Confirm allowed_operations matches the slugs you passed. Check target_type is correct and exactly one of tenant_data_source_id, tenant_app_id, tenant_ai_tool_id is set (rest null) for FK-targeted types.
References
- references/operation-catalog.md — All operation slugs grouped by target type, with display names and intended use.
- references/workflow-examples.md — End-to-end worked example: create two roles with data-source and settings rules, add a role query, validate, and test.
1---
2name: docyrus-acl-design
3description: Design, configure, and validate a Docyrus tenant ACL (Access Control Layer) end-to-end using the `docyrus acl` CLI commands. Use when the user wants to define permission roles, assign operation-level permissions to roles for data sources / apps / AI tools / settings / devtools, set up row-level record filters (role queries), build an organizational hierarchy (hierarchy units), or look up available system operations. Triggers on "create a role", "set permissions for a role", "grant access to a data source", "role query", "row-level filter", "hierarchy unit", "org-chart access", "acl rules", "what operations", `docyrus acl roles`, `docyrus acl rules`, `docyrus acl role-queries`, `docyrus acl hierarchy-units`, `docyrus acl operations`, or any ACL role/permission design + configuration task in Docyrus.
4metadata:
5 source: https://skillmd.com/skills/docyrus/docyrus-acl-design
6---
7
8# Docyrus ACL Design
9
10Configure tenant access control with `docyrus acl`, then **validate** the setup before handing it off. The Docyrus ACL system has five concepts:
11
12| Concept | What it is |
13|---|---|
14| **Role** | Named permission group assigned to users |
15| **Hierarchy Unit** | Org-tree node for org-chart-aware row-level security (RLS) |
16| **Role Query** | Row-level filter attached to one or more roles for a data source |
17| **Operation** | System-defined permission slug (read-only — you can't create these) |
18| **Rule** | Binds a role to a target (data source / app / AI tool / settings) with a list of allowed operation slugs |
19
20For platform concepts see the **docyrus-platform** skill. For CLI flag tables see the **docyrus-cli-app** skill. This skill is the ACL-specific workflow.
21
22## Workflow
23
24Follow in order. A role without rules grants nothing useful.
25
261. **Confirm auth.**
27 ```bash
28 docyrus auth who --json # confirm session + tenant
29 ```
30 No session → stop and ask the user to run `docyrus auth login`.
31
322. **Survey available operations.** Before creating rules, know which operations exist per target type:
33 ```bash
34 docyrus acl operations list --targetType data_source --json
35 docyrus acl operations list --targetType settings --json
36 docyrus acl operations list --targetType devtools --json
37 ```
38 The full catalog is in [references/operation-catalog.md](references/operation-catalog.md).
39
403. **Create roles.** See [Roles](#roles). One role per logical access level (e.g. "Viewer", "Editor", "Admin"). If the role is app-scoped pass `--tenantAppId`.
41
424. **Create hierarchy units** (skip if org-chart RLS is not needed). See [Hierarchy Units](#hierarchy-units). Build parent units before children.
43
445. **Create role queries** (skip if row-level record filtering is not needed). See [Role Queries](#role-queries). Each role query narrows which records a role can see in a specific data source.
45
466. **Create rules.** Each rule grants a role a set of operations on one specific target. See [Rules](#rules). Start with `data_source` rules, then `settings`, `devtools`, `app`, `ai_tool` as needed.
47
487. **Validate.** Re-read each object to confirm it landed with the right values. See [Validate](#validate).
49
50A full worked example (two-role CRM setup with data-source rules, a settings rule, and a role query) is in [references/workflow-examples.md](references/workflow-examples.md).
51
52## Roles
53
54```bash
55# List roles (optionally filter by name/slug)
56docyrus acl roles list --json
57docyrus acl roles list --search "editor" --json
58
59# Get one role
60docyrus acl roles get --roleId <uuid> --json
61
62# Create a role
63docyrus acl roles create --slug "crm-viewer" --name "CRM Viewer" --json
64docyrus acl roles create --slug "crm-editor" --name "CRM Editor" \
65 --tenantAppId <app-uuid> --ownership CUSTOM --json
66
67# Update a role (PATCH — any subset of fields)
68docyrus acl roles update --roleId <uuid> --name "CRM Viewer (Read-Only)" --json
69
70# Delete a role and all its assignments
71docyrus acl roles delete --roleId <uuid> --json
72```
73
74Key fields:
75- `--slug` and `--name` are **required** on create.
76- `--ownership` ∈ `SYSTEM | CUSTOM | APP | USER | PRODUCT` (default `CUSTOM`).
77- `--tenantAppId` scopes the role to a specific app.
78- `--disableLogin` (int 0/1) prevents login when the user only holds this role.
79- `--activitySummaryReportQueryId` points to a custom query UUID for the role's activity summary dashboard.
80- `--data '<json>'` / `--from-file ./payload.json` override individual flags.
81
82## Hierarchy Units
83
84Hierarchy units form an org-chart tree. Users are then assigned to units, and data-source `data_access`/`unit_peer_access` rules use that tree for RLS.
85
86```bash
87# List units (optionally filter by parent or name)
88docyrus acl hierarchy-units list --json
89docyrus acl hierarchy-units list --parentId <uuid> --json
90docyrus acl hierarchy-units list --search "sales" --json
91
92# Get one unit
93docyrus acl hierarchy-units get --unitId <uuid> --json
94
95# Create (build parents before children)
96docyrus acl hierarchy-units create --name "Sales" --json
97docyrus acl hierarchy-units create --name "Sales East" --parentId <sales-unit-uuid> --json
98
99# Update
100docyrus acl hierarchy-units update --unitId <uuid> --name "Sales West" --json
101
102# Delete (fails if the unit has children — delete children first)
103docyrus acl hierarchy-units delete --unitId <uuid> --json
104```
105
106- `--name` is **required** on create.
107- `--parentId` is optional; omit for a root unit.
108
109## Role Queries
110
111A role query is a DSQL-style filter object attached to one or more roles for a specific data source. Users whose active role matches are restricted to only the rows that match the query.
112
113```bash
114# List role queries
115docyrus acl role-queries list --json
116docyrus acl role-queries list --dataSourceId <uuid> --json
117docyrus acl role-queries list --roleId <uuid> --json
118docyrus acl role-queries list --restrictionLevel hidden --json
119
120# Get one
121docyrus acl role-queries get --roleQueryId <uuid> --json
122
123# Create
124docyrus acl role-queries create \
125 --roleIds "<role-uuid-1>,<role-uuid-2>" \
126 --dataSourceId <ds-uuid> \
127 --query '{"field":"status","operator":"eq","value":"active"}' \
128 --restrictionLevel "read-only" \
129 --json
130
131# Update
132docyrus acl role-queries update --roleQueryId <uuid> \
133 --query '{"field":"status","operator":"in","value":["active","pending"]}' --json
134
135# Delete
136docyrus acl role-queries delete --roleQueryId <uuid> --json
137```
138
139Key fields:
140- `--roleIds` comma-separated UUIDs — **required** on create.
141- `--query` JSON string of the filter object — **required** on create.
142- `--dataSourceId` scopes the query to one data source (optional — omit for a global filter).
143- `--restrictionLevel` ∈ `hidden | read-only | not-deletable`.
144- `--filterChildRelations` boolean — also apply the filter to child-relation queries.
145
146## Operations
147
148Operations are system-defined and **read-only** — you can list them but cannot create, modify, or delete them.
149
150```bash
151# List all operations
152docyrus acl operations list --json
153
154# Filter by target type
155docyrus acl operations list --targetType data_source --json
156docyrus acl operations list --targetType settings --json
157docyrus acl operations list --targetType devtools --json
158docyrus acl operations list --targetType ai --json
159docyrus acl operations list --targetType ai_tool --json
160docyrus acl operations list --targetType field --json
161
162# Search by name or slug
163docyrus acl operations list --search "delete" --json
164docyrus acl operations list --search "manage" --targetType settings --json
165```
166
167`--targetType` values: `data_source`, `field`, `ai`, `settings`, `devtools`, `app`, `ai_tool`.
168The full operation catalog (slugs + names per target type) is in [references/operation-catalog.md](references/operation-catalog.md).
169
170## Rules
171
172A rule grants a role a set of operations on exactly one target. One rule = one (role × target) binding.
173
174```bash
175# List rules
176docyrus acl rules list --json
177docyrus acl rules list --roleId <uuid> --json
178docyrus acl rules list --targetType settings --json
179docyrus acl rules list --dataSourceId <uuid> --json
180docyrus acl rules list --appId <uuid> --json
181docyrus acl rules list --aiToolId <uuid> --json
182docyrus acl rules list --includeArchived --json # default: archived rules are hidden
183
184# Get one rule
185docyrus acl rules get --ruleId <uuid> --json
186
187# Create a rule
188# data_source target (default)
189docyrus acl rules create \
190 --roleId <role-uuid> --dataSourceId <ds-uuid> \
191 --allowedOperations "view,create,edit,delete" --json
192
193# settings target (no FK — omit dataSourceId/appId/aiToolId)
194docyrus acl rules create \
195 --roleId <role-uuid> --targetType settings \
196 --allowedOperations "manage_users,manage_teams" --json
197
198# devtools target
199docyrus acl rules create \
200 --roleId <role-uuid> --targetType devtools \
201 --allowedOperations "cody,studio" --json
202
203# ai_tool target
204docyrus acl rules create \
205 --roleId <role-uuid> --targetType ai_tool --aiToolId <tool-uuid> \
206 --allowedOperations "allow" --json
207
208# Update a rule (PATCH — supply only what changes)
209docyrus acl rules update --ruleId <uuid> \
210 --allowedOperations "view,create,edit,delete,export" --json
211
212# Archive a rule (soft disable — still visible with --includeArchived)
213docyrus acl rules update --ruleId <uuid> --archived true --json
214
215# Restore an archived rule
216docyrus acl rules update --ruleId <uuid> --archived false --json
217
218# Hard-delete a rule
219docyrus acl rules delete --ruleId <uuid> --json
220```
221
222Key fields:
223- `--roleId` is **required** on create.
224- `--targetType` defaults to `data_source`; valid values: `data_source`, `field`, `ai`, `settings`, `devtools`, `app`, `ai_tool`.
225- `--allowedOperations` comma-separated list of operation slugs; must match real slugs for the target type.
226- FK fields are mutually exclusive per rule row: set `--dataSourceId` for `data_source` targets, `--appId` for `app` targets, `--aiToolId` for `ai_tool` targets. Leave all three null for `settings`, `devtools`, `ai`, `field` targets.
227
228## Critical rules
229
230- **All payload keys are camelCase.** `--roleId`, `--dataSourceId`, `--allowedOperations`, `--roleIds`, `--targetType` — never snake_case. The backend ACL DTOs are camelCase and `GlobalValidationPipe` does NOT transform snake_case → camelCase.
231- **One rule per (role × target FK).** A unique database constraint prevents two rules for the same `(tenant, role, dataSource)`, `(tenant, role, app)`, or `(tenant, role, aiTool)`. Attempting to create a duplicate returns a 500 constraint error. Check with `rules list --roleId <id>` first.
232- **`targetType` defaults to `data_source`** on `rules create` — always pass it explicitly when creating non-data-source rules to avoid accidentally creating a `data_source` rule with null FK.
233- **`--allowedOperations` is comma-separated** on the CLI — it becomes a `string[]` in the request. Spaces around commas are stripped.
234- **`--roleIds` is comma-separated** for role queries (same pattern).
235- **`--query` must be a JSON string** for role queries — wrap in single quotes: `--query '{"field":"owner","operator":"eq","value":"{{userId}}"}'`.
236- **Operations are read-only.** You cannot create or modify `core_acl_operation` rows — only a superadmin can. Use `acl operations list` to discover slugs; pass them into `--allowedOperations`.
237- **Hierarchy unit delete rejects units with children.** Delete leaves first, then parents.
238- **Archive ≠ delete.** `rules update --archived true` soft-disables a rule (the row stays and is hidden from normal list results). `rules delete` hard-removes it. Prefer archive when you may want to restore later.
239- **`--targetType` uses underscores** (`data_source`, `ai_tool`), not hyphens.
240- **`--restrictionLevel` for role queries uses hyphens** (`read-only`, `not-deletable`), not underscores.
241- **Validate then test.** After configuring roles + rules, log in as a user with that role and confirm the access behaves as expected.
242
243## Validate
244
245After authoring, confirm each object landed correctly:
246
2471. **Roles:**
248 ```bash
249 docyrus acl roles list --json # count matches
250 docyrus acl roles get --roleId <id> --json # slug, name, ownership, tenantAppId
251 ```
252
2532. **Hierarchy units:**
254 ```bash
255 docyrus acl hierarchy-units list --json # tree structure
256 docyrus acl hierarchy-units list --parentId <id> --json # children of a node
257 ```
258
2593. **Role queries:**
260 ```bash
261 docyrus acl role-queries list --roleId <id> --json # confirm query + restrictionLevel
262 ```
263
2644. **Rules:**
265 ```bash
266 docyrus acl rules list --roleId <id> --json # all rules for the role
267 docyrus acl rules get --ruleId <id> --json # confirm allowedOperations, targetType, FK
268 ```
269 Confirm `allowed_operations` matches the slugs you passed. Check `target_type` is correct and exactly one of `tenant_data_source_id`, `tenant_app_id`, `tenant_ai_tool_id` is set (rest null) for FK-targeted types.
270
271## References
272
273- **[references/operation-catalog.md](references/operation-catalog.md)** — All operation slugs grouped by target type, with display names and intended use.
274- **[references/workflow-examples.md](references/workflow-examples.md)** — End-to-end worked example: create two roles with data-source and settings rules, add a role query, validate, and test.