Availability is a decision chain
In KayanOS, an item being visible is not the same as being usable. A menu entry can be present while a record action is refused; a form can be published while a public user cannot start it; an entity can exist while an API token cannot discover it. Treat availability as a chain of independent checks:- Organization and identity — the member, public participant, or integration is in the intended organization and is active.
- Released surface — the capability is part of the released KayanOS product and appears in the applicable navigation or route. Navigation is a convenience check, not authorization.
- Resource and verb — the role grants the required action on the target resource, such as opening, listing, creating, updating, deleting, approving, or administering.
- Scope and hierarchy — the grant must intersect with the record’s assigned scope or permitted hierarchy relation.
- Object state — the entity, field, form version, status transition, dashboard, or connection is configured and in a state that permits the operation.
- Runtime boundary — server-side validation, field rules, retention, rate limits, connection authorization, or publication conditions still accept the request.
Do not solve a denial by giving an organization-wide administrator role first. Identify the first failed check, correct the smallest approved configuration or permission, and repeat the same test with a member who should remain denied.
The permission model: resource, verb, and scope
A KayanOS grant combines three questions:
The exact set of verbs is resource-specific. Do not assume a
list grant permits open, or that an open grant permits an update. A user-interface helper may decide to show a button when the member has any matching verb token, while the server later evaluates the record’s actual scopes and the requested operation. The server-side result is authoritative.
Scopes are not display labels
A scope is an access boundary carried by roles and records. A record can have one or more scopes, and a member must have a matching token for an operation that requires scoped access. An unscoped screen or list entry does not prove that the member can act on every result. For hierarchy-aware role assignments, KayanOS can apply a role to the selected object in one of three ways:
Use the smallest relationship that expresses the job. “Descendants” is powerful; check the complete hierarchy and future child-creation process before assigning it.
Visibility, selection, saving, and delivery are separate
The most common access mistake is treating one successful step as proof that every later step is authorized.
This separation is intentional. Keep visibility rules readable, but place actual authorization and state-transition enforcement in the relevant KayanOS service policy.
A practical access design for the Directorate
The following is a design exercise, not a set of built-in roles. Build it in a non-production organization first, then map it to the exact released resources and verbs shown in the role editor.
Write the intended outcome before selecting a role. Avoid creating a generic “manager” role that becomes a collection of unrelated grants.
Configure access safely
- Name the outcome. For example: “An inspector may update an inspection record at an assigned Centre but may not approve a Citizen Service Request.”
- Identify the resource and the exact action. Use the resource and verb labels in the role editor; do not substitute an assumed label from a different feature.
- Choose the narrowest scope. Prefer Exact while validating. Add an ancestor/descendant relationship only when the organization hierarchy explicitly requires it.
- Assign a test member. Use a controlled member account with no extra roles that could make the test pass accidentally.
- Test the allowed path. Confirm the target record/action succeeds and the saved result is visible only where expected.
- Test the denied path. Try the same operation on a different Centre, protected field, unpublished form/version, or unavailable transition. It must remain denied.
- Record the decision. Keep the role, scope boundary, resource/verb, test record reference, reviewer, and change reason in the organization’s change record.