> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and access

> Design least-privilege roles, verbs, and scopes for KayanOS services, then prove the result with a controlled access test.

Access in KayanOS is part of the service design. A title such as “manager,” “inspector,” or “administrator” is not enough on its own; the system evaluates which resource a member may act on, which verb is assigned, and whether the record lies in an allowed scope. A safe role lets someone complete their responsibility without exposing unrelated citizen data or configuration.

This guide uses a Citizen Services Directorate scenario. The team manages request `CSR-2026-00042`, its related inspection, scheduled event, evidence files, and decision. Use the example to model responsibility; do not copy access grants without checking your organization’s policies and hierarchy.

## Goal

Create a role model that answers four questions for every person: what can they see, what can they do, where can they do it, and how will you prove that the boundary works?

## The access model

Think about each grant as a three-part statement:

> **Resource** + **verb** + **scope**

For example, “update inspections in the North Service Center” is more precise than “make this person an inspector.” The resource is `inspections`; the action is update; the scope is the approved service-center or hierarchy token that covers the inspection.

| Part       | Question to ask                                           | Example                                                                             |
| ---------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Resource   | What data or feature is protected?                        | Service requests, inspections, events, files, forms, roles                          |
| Verb       | What is the member allowed to do?                         | List, open, create, update, delete, share, or a configured resource-specific action |
| Scope      | Where does that verb apply?                               | Organization, node, service center, form, or another assignable resource scope      |
| Assignment | Which member, position, group, or rule receives the role? | Field Inspector role for members assigned to the North Service Center               |

KayanOS checks these separately. A member may be allowed to list a queue but not open every record; open a file but not edit it; edit a record but not share it; or see an event but not delete it. Do not tell staff that a sidebar item guarantees a save, share, or delete action.

## When to use roles, assignments, and scopes

Use a role when several people need the same reusable responsibility. Use a scoped assignment when that responsibility must be limited to a location, organizational branch, form, or other approved boundary. Use a direct exception only when the policy truly requires it, and document why it exists.

Where the chosen hierarchy supports it, KayanOS can express an assignment at the exact target, its ancestors, or its descendants. Select the narrowest interpretation that matches the policy:

| Scope choice | Appropriate use                                                      | Risk if used too broadly                                                        |
| ------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Exact        | A service-center supervisor manages only that center                 | The role may miss legitimate work in child units if the service is hierarchical |
| Ancestors    | A local role needs a documented path to the parent unit’s records    | The member may see higher-level work that should remain centralized             |
| Descendants  | A regional manager is accountable for a region and its child centers | A regional role can expose unrelated local work if the region is too broad      |

Do not use hierarchy expansion as a shortcut for a missing business rule. First confirm the service boundary, then select the scope behavior that implements it.

## A practical Citizen Services role map

Start with a small set of operational responsibilities. Your exact entity names and scopes will differ, but the accountability pattern should remain clear.

| Role                       | Typical responsibility                                | Minimum useful access                                                                                       | Deliberately excluded access                                                              |
| -------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Registry Officer           | Receive and check intake                              | List/open/create/update service requests in the intake scope; create or update assigned completeness tasks  | Change organization settings, issue formal decisions, browse other service centers        |
| Service Manager            | Own triage, allocation, and exceptions                | Open/update requests in the managed scope; assign work; create related inspections/events                   | Edit role definitions or unrestricted evidence outside the service scope                  |
| Field Inspector            | Perform and record an inspection                      | Open assigned/request-scoped work; create/update inspections; upload approved evidence                      | Modify final decision status or share restricted folders without permission               |
| Records Officer            | Control documents and final record quality            | Open request and inspection evidence; update approved document metadata; share files only in approved scope | Reassign operational ownership or delete records outside retention policy                 |
| Authorized Reviewer        | Make a designated decision                            | Open the complete decision packet; perform the configured status/action/signature step                      | Broaden their own role, replace evidence, or edit unrelated requests                      |
| Organization Administrator | Maintain member, role, and organization configuration | Role administration only where the appropriate roles verbs are assigned                                     | Assume operational ownership of all requests merely because they administer configuration |

The role table is a design starting point, not a default permission set. Every “minimum useful access” entry must be mapped to real resources, verbs, and scopes in your organization.

## Configure a role deliberately

1. **Map the handoff before opening settings.** Write the service status, responsible role, next action, and evidence required for each stage of the request.
2. **Choose the role scope.** Decide whether the role applies across the organization, to a selected hierarchy target, or to an eligible form/resource scope. Do not choose organization-wide scope only because it is quicker.
3. **Select resources and verbs.** Add only the records and forms needed for the role’s own work. Keep list/open/create/update/delete/share decisions separate.
4. **Assign the role to the right recipients.** Use the approved member, position, group, or assignment approach. Check that an inactive or transferred staff member does not retain access through an obsolete assignment.
5. **Save one controlled change at a time.** Record the reason, policy owner, resource, verbs, scope, and review date for meaningful access changes.
6. **Test with a non-owner member.** A role designer’s own broad access can hide a mistake. Test with a member who has only the role under review.
7. **Review after organizational changes.** Re-test when a service center moves, a position changes, a form is published, or a new related entity becomes part of the workflow.

Opening, creating, and updating role definitions are separate role-management capabilities. If a person can inspect an assignment but cannot save a change, that can be an intentional boundary rather than a system error.

## Run an access test matrix

Use an approved non-production request and record both positive and negative results. The goal is not only to prove that the intended action works, but also that unrelated data remains unavailable.

| Test member                          | Expected allowed action                            | Expected denied action                                        | Evidence to record                                      |
| ------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------- |
| Registry Officer in the intake scope | Create and update a received request               | Open a request belonging only to another service-center scope | Queue result, record screen, save result, denial result |
| Field Inspector                      | Update the assigned inspection and upload evidence | Change the final request decision                             | Inspection activity and denied decision control         |
| Records Officer                      | Download and share an approved evidence file       | Permanently delete a restricted folder                        | File action result and absence/denial of delete action  |
| Service Manager                      | Assign task and create a scheduling event          | Edit role definitions                                         | Task/event result and role-settings denial              |
| Authorized Reviewer                  | Complete the configured decision/signature step    | Change unrelated organization settings                        | Decision evidence and denied configuration path         |

Test navigation as well as actions. A member might not see a dynamic application entry if they lack list/create/initiate access, or might reach a link but receive a permission denial when opening the target record. Both results matter.

## Expected result

Every service participant has a short, explainable role. A service owner can point to a request and say why a member can list it, why another member can update it, and why a third member cannot download or delete its evidence. The organization does not rely on shared administrator accounts or broad temporary grants to keep work moving.

## Safe testing

Use controlled data and test members. Do not remove a real staff member’s production access solely to see a denial. Instead, create a temporary test assignment in the approved non-production context, run the matrix, save the results, and remove the temporary assignment. Never put real citizen data in a role-testing record.

## Troubleshooting

| Problem                                        | What to check                                                                                                               |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| The role page opens but Save is denied         | The member may have the role open verb but not the update verb; ask the authorized role administrator to review the request |
| A user sees a menu item but no records         | Listing and opening may be limited by resource scope, or the dynamic navigation item may require a verb the member lacks    |
| A record opens but fields/actions are disabled | Check the update verb, record scope, field-specific controls, and whether the record is in a controlled state               |
| A person retained access after transfer        | Review every member, position, group, and hierarchy-based assignment that can grant the role                                |
| A regional role sees too much data             | Revisit ancestor/descendant selection and replace broad hierarchy scope with the smallest service boundary                  |
| A quick exception keeps becoming permanent     | Replace individual ad-hoc grants with a documented role or redesign the handoff so the accountable role can act safely      |

## Related guides

* See how availability affects navigation in [Navigate KayanOS](/start/navigate-kayanos).
* Apply the model to the complete service path in [Explore an example workspace](/start/example-workspace).
* Read the platform-wide reference in [Permissions and availability](/reference/permissions-and-availability).
* Design fields and record visibility in [Entity fields and layouts](/build/entity-fields-and-layouts).
* Learn controlled file access in [Library](/work/library).

![KayanOS role assignment for a public-service organization service manager.](https://kayanos.app/docs-images/en/start/roles-and-access.png)