> ## 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 scopes

> Configure least-privilege access as resource, verb, and scope assignments, then prove both allowed and denied outcomes with real service work.

Roles turn an operating responsibility into controlled access. They are not job titles, menu labels, or a way to make a blocked button disappear. KayanOS evaluates a protected resource, the assigned verb, and the scope of the actual record. A person can therefore see a service category but still be unable to open a record, save a change, share a file, delete an event, or perform a formal decision.

Use this guide to configure roles for the Directorate of Citizen Services. The same method applies to any organization: name the responsibility, identify the smallest set of resources and verbs, select the correct scope, assign the role, and test it as a non-owner.

## Goal

Build explainable roles that let Registry, Field Inspection, Decision and Records, and organization administration teams complete their work without expanding access across unrelated Service Centres or records.

## The access model

Every grant should read as a sentence:

> **This role may perform this verb on this resource in this scope.**

| Part     | Question                   | Directorate example                                                                        |
| -------- | -------------------------- | ------------------------------------------------------------------------------------------ |
| Resource | What is being protected?   | Citizen Service Requests, Inspections, files, forms, events, members, or roles             |
| Verb     | What may the member do?    | List, open, create, update, delete, share, initiate, or a resource-specific action         |
| Scope    | Where does the verb apply? | One Service Centre, locality hierarchy, organization, form, or another assignable boundary |
| Assignee | Who receives the role?     | A member, position, group, or approved assignment rule                                     |

The distinction matters. **List** does not automatically mean **open**; **open** does not mean **update**; **update** does not mean **share** or **delete**. Navigation can be generated for an entity when a member has a useful list or create path, but an entry in the menu is not a promise that every record or action is allowed.

## Scope choices and inheritance

Where the selected hierarchy supports it, a role assignment can apply to the exact target, its ancestors, or its descendants.

| Scope choice | Use it when                                                                   | Risk to test                                                                            |
| ------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Exact        | A Registry Officer works only in North Service Centre                         | The officer cannot see a legitimate record that is stored in an approved child boundary |
| Ancestors    | A local assignment needs a documented parent-level path                       | Higher-level records become visible when they should remain centralized                 |
| Descendants  | A regional manager is accountable for a region and all approved child centres | The selected region is too broad and exposes an unrelated locality                      |

Do not select an inherited scope merely because it makes a missing record appear. First establish the business boundary; then test a record inside and outside that boundary. Scope is enforced against the record’s applicable scope tokens, not merely as a visual filter.

## Design the service roles before opening the editor

Start with a short responsibility map. The following is a starting pattern, not a ready-made permission set:

| Role                         | Required outcome                                               | Minimum useful access                                                                                     | Do not assume                                                       |
| ---------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Registry Officer             | Register and return incomplete requests for one Service Centre | List/open/create/update intake requests in that centre; update assigned completeness tasks                | Access to other centres, organization settings, or a final decision |
| Field Inspector              | Record an assigned inspection                                  | Open relevant request/inspection work; create/update inspections in field scope; upload approved evidence | Permission to change the final decision or share every file         |
| Decision and Records Officer | Review evidence and controlled documents                       | Open the decision packet; update approved document metadata or file actions in scope                      | Operational ownership of every request or unrestricted deletion     |
| Service Manager              | Allocate work and manage the service lifecycle                 | Open/update requests in managed scope; create tasks/events; review exceptions                             | Role administration simply because the person is a manager          |
| Organization Administrator   | Maintain configuration                                         | Role, member, language, homepage, or other settings only when the corresponding verbs are assigned        | Automatic operational ownership of all citizen requests             |

For each row, list the action that must remain denied. A role is not complete until it has an intended boundary.

## Configure a role deliberately

1. Open **Administration → Roles and scopes** and verify that you have the relevant role-management permission. Opening, creating, and updating roles are separate capabilities.
2. Choose the role’s administration scope: organization-wide, an eligible hierarchy boundary, a form, or another supported scope. Do not use organization scope as a temporary shortcut.
3. Name the role after the responsibility, for example **North Service Centre Registry Officer**, and describe the business purpose and review owner.
4. In the permissions area, select only the resources the role needs. For each resource, select the actual verbs separately.
5. Where an assignment permits hierarchy selection, choose **Exact**, **Ancestors**, or **Descendants** intentionally. Record the rationale in the change record.
6. Assign the role to the approved member, position, group, or rule-derived recipient. Check whether an inherited assignment from a position or group will also grant it.
7. Save one role change at a time. Avoid copying a broad existing administrator role just to resolve one exception.
8. Refresh the allowed member context as required and test navigation, list, open, create, update, share/download, and delete actions that matter to the service.

The permission editor surfaces resources eligible for the selected scope. If an entity or form is absent, verify the entity/form configuration and assignable scope before trying to compensate with a broader role.

## Test the Citizen Service Request boundary

Create two approved non-production requests: one in North Service Centre and one in a different locality. Give each test member only the role being evaluated. Then record the following matrix:

| Test member                | Must be allowed                                    | Must be denied                                                             |
| -------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
| Registry Officer, North    | Create and update a received North request         | Open or update the other locality’s restricted request                     |
| Field Inspector            | Update assigned inspection findings in field scope | Change the request’s final controlled decision                             |
| Records Officer            | Open/share the approved evidence folder in scope   | Permanently delete a restricted folder or change unrelated service data    |
| Service Manager            | Assign a task and schedule an event                | Edit role definitions unless role-management access was separately granted |
| Organization Administrator | Maintain the approved setting                      | Assume access to a citizen record outside a granted service scope          |

Record the route, member, resource, verb, record scope, expected outcome, actual outcome, and reviewer. A failed negative test is useful evidence: it means the boundary needs correction before publishing, not that the test member needs broader access.

## Change control and review

Review a role when a staff member transfers, a position changes, a group changes, a Service Centre moves in the hierarchy, a form becomes published, or a new related entity becomes part of a service. Check both direct and inherited assignments.

Before deleting or narrowing a role, inventory its active use. A role change can remove a user’s ability to complete a task, open an evidence file, or access a form that is still part of an active service path. Plan the handoff first; do not use a shared organization-owner account to bridge a gap.

## Troubleshooting

| Symptom                                         | Check                                                      | Safe response                                                               |
| ----------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| A member cannot see an application/entity entry | Published placement plus list/create/initiate verbs        | Grant only the required verb in the intended scope                          |
| The list is visible but a record will not open  | Open verb and the record’s actual scope tokens             | Compare an allowed and denied record; do not change the whole role blindly  |
| Save or Delete is unavailable                   | Update/delete verb, record scope, field/action state       | Request the smallest action needed for the responsibility                   |
| A role editor Save is denied                    | The current member may open roles but lack role update     | Use an authorized role administrator; do not share their account            |
| A regional role sees too much                   | Ancestor/descendant setting and inherited assignment path  | Replace it with the narrowest exact or branch scope and retest              |
| Access remains after a transfer                 | Direct role, position/group assignment, and hierarchy rule | Remove every obsolete assignment and test with the member’s current context |

## Related guides

* Manage the people receiving roles in [Manage members](/admin/manage-members).
* Learn the everyday access model in [Roles and access](/start/roles-and-access).
* Use controlled evidence access in [Library](/work/library).
* Diagnose visibility and action failures in [Permissions and availability](/reference/permissions-and-availability).

![KayanOS role and scope configuration for Directorate of Citizen Services staff.](https://kayanos.app/docs-images/en/admin/roles-and-scopes.png)