Roles and access - KayanOS Documentation

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

Map the handoff before opening settings. Write the service status, responsible role, next action, and evidence required for each stage of the request.
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.
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.
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.
Save one controlled change at a time. Record the reason, policy owner, resource, verbs, scope, and review date for meaningful access changes.
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.
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

See how availability affects navigation in Navigate KayanOS.
Apply the model to the complete service path in Explore an example workspace.
Read the platform-wide reference in Permissions and availability.
Design fields and record visibility in Entity fields and layouts.
Learn controlled file access in Library.

KayanOS role assignment for a public-service organization service manager.

​Goal

​The access model

​When to use roles, assignments, and scopes

​A practical Citizen Services role map

​Configure a role deliberately

​Run an access test matrix

​Expected result

​Safe testing

​Troubleshooting

​Related guides