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

# Permissions and availability

> Diagnose why a KayanOS capability, record, action, or field is visible, unavailable, or refused without widening access by guesswork.

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

1. **Organization and identity** — the member, public participant, or integration is in the intended organization and is active.
2. **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.
3. **Resource and verb** — the role grants the required action on the target resource, such as opening, listing, creating, updating, deleting, approving, or administering.
4. **Scope and hierarchy** — the grant must intersect with the record's assigned scope or permitted hierarchy relation.
5. **Object state** — the entity, field, form version, status transition, dashboard, or connection is configured and in a state that permits the operation.
6. **Runtime boundary** — server-side validation, field rules, retention, rate limits, connection authorization, or publication conditions still accept the request.

![KayanOS permissions and availability guidance for a public-service organization member.](https://kayanos.app/docs-images/en/reference/permissions-and-availability.png)

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:

| Part     | Question                  | Citizen Service Request example                                                                                     |
| -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Resource | What is being controlled? | `service_requests`, a form, a dashboard, an API-token administration surface, or another released resource.         |
| Verb     | What may the member do?   | List, open, create, update, delete, submit, approve, or administer—only the verbs configured for that resource.     |
| Scope    | Where may the verb apply? | The Central Service Centre, a locality, an organizational unit, a form-specific scope, or another assignable scope. |

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:

| Assignment choice | Intended result                                                      | Example                                                                                           |
| ----------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Exact             | Apply only to the selected Service Centre or organizational node.    | An intake clerk works only at Central Service Centre.                                             |
| Ancestors         | Apply to the selected object and the configured parent relationship. | A manager can work at a locality and its parent service area when that is the approved hierarchy. |
| Descendants       | Apply to the selected object and its child relationship.             | A regional manager can supervise approved child Service Centres.                                  |

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.

| What the person sees            | What it proves                                                        | What it does **not** prove                                                       |
| ------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| A navigation item               | The client made the route discoverable.                               | That a specific record can be opened or changed.                                 |
| An entity in a selector         | The current configuration exposes an option.                          | That the member can read every field or save a related record.                   |
| A visible form                  | The form/version is available to this audience.                       | That the session can be submitted, signed, or transitioned.                      |
| A dashboard widget              | The layout is visible.                                                | That the viewer receives data beyond their record access.                        |
| An API entity definition        | The entity is explicitly API-enabled and the token has a usable verb. | That protected fields are readable/queryable or write operations are allowed.    |
| An automation step in an editor | The step is available to configure.                                   | That its connection, target, runtime permission, or trigger filter will succeed. |

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.

| Job                       | Needed outcome                                                          | Narrow starting boundary                                                                                          | Deliberate denial test                                                                         |
| ------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Registry and Intake Unit  | Create and review requests at one Service Centre.                       | Create/list/open the request resource at the exact Centre scope.                                                  | Attempt to update a request assigned only to another Centre.                                   |
| Field Inspection Team     | Open assigned requests and submit inspection evidence.                  | Open/update only assigned inspection/request scopes; use the released form/session actions required for evidence. | Attempt to change the decision status or open an unrelated locality's request.                 |
| Decision and Records Unit | Review complete evidence and move a request through approved decisions. | Approved update/transition verbs at the decision unit scope.                                                      | Attempt an unavailable transition or a field update outside the unit scope.                    |
| Service manager           | Monitor workload and adjust approved team assignments.                  | Dashboard/list access plus the smallest hierarchy scope required for managed Centres.                             | Verify a hidden/protected field remains unavailable in a widget or export.                     |
| Organization owner        | Change organization-wide configuration.                                 | Administration verbs only for the owner role.                                                                     | Use a manager account to confirm organization settings and token administration remain denied. |

Write the intended outcome before selecting a role. Avoid creating a generic “manager” role that becomes a collection of unrelated grants.

## Configure access safely

1. **Name the outcome.** For example: “An inspector may update an inspection record at an assigned Centre but may not approve a Citizen Service Request.”
2. **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.
3. **Choose the narrowest scope.** Prefer Exact while validating. Add an ancestor/descendant relationship only when the organization hierarchy explicitly requires it.
4. **Assign a test member.** Use a controlled member account with no extra roles that could make the test pass accidentally.
5. **Test the allowed path.** Confirm the target record/action succeeds and the saved result is visible only where expected.
6. **Test the denied path.** Try the same operation on a different Centre, protected field, unpublished form/version, or unavailable transition. It must remain denied.
7. **Record the decision.** Keep the role, scope boundary, resource/verb, test record reference, reviewer, and change reason in the organization’s change record.

When modifying an existing role, inspect all current assignees first. A change to one role can widen access for many members at once.

## Feature-specific availability checks

| Capability          | Additional condition to verify                                                                                                                                    |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entity records      | Entity configuration, field-level read/edit rules, record scopes, and the operation’s lifecycle/state policy.                                                     |
| Forms               | Correct form/version, audience and publication state, session ownership/read-only state, required signature/action rules, and any offline capability restriction. |
| Public portal       | A published regular form, public enablement, date/limit/account conditions, and the public participant’s permitted session boundary.                              |
| Dashboards          | Viewer access, selected data source/widget configuration, and the viewer’s underlying data access. A dashboard never grants source-record access.                 |
| Document templates  | Template availability, record context, selected caller/admin execution mode, and template-specific lookup restrictions.                                           |
| Public API          | Explicit entity enablement, active token owner, verb/scope access, field visibility, and a current token.                                                         |
| KayanOS Automations | A valid organization-scoped KayanOS connection, released trigger/action, target availability, runtime permissions, and trigger/filter match.                      |

## Diagnose what happened

Collect evidence without copying secrets or private record data: page URL, time and timezone, organization, member/role name, target resource and record reference, scopes involved, action attempted, visible error text, and a non-sensitive screenshot. For an API or automation failure, also retain the request ID or run ID.

| Symptom                                    | Likely failed check                                                     | First evidence to inspect                                                                   |
| ------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Menu or app is absent                      | Released surface, organization context, or route visibility             | Organization selection, signed-in identity, and the released navigation configuration.      |
| Record appears in a list but will not open | Open verb or record-scope intersection                                  | The record's scopes and the member’s matching role tokens.                                  |
| Save/update is refused                     | Update verb, field rule, scope, or lifecycle validation                 | Exact field/action, record status, and server response—not only the button state.           |
| Selector is empty                          | List/open permission, source configuration, or filtered scope           | Source entity/form state, selected scope, and whether the member can read eligible choices. |
| Public form cannot start                   | Publication, regular-form eligibility, end date/limit/account condition | Published version, portal configuration, and the public session rule.                       |
| Dashboard is blank or shows denial         | Widget source permission or query configuration                         | Viewer role/scope, widget filter, and source-record access.                                 |
| Integration sees `403` or field omission   | Token owner verb/scope or field read restriction                        | `/me`, entity metadata, token owner role, and public field policy.                          |
| Automation run refuses a step              | Connection, target, permission, or filter mismatch                      | Connection state, target release/publication state, run ID, and trigger data.               |

## Testing and change control

Use an approved non-production Citizen Service Request with no personal data. Test once as the intended role and once as a role that should remain denied. Include a hierarchy edge case—such as the Central Service Centre and a different locality—before approving any ancestor or descendant scope.

For a production change, use a small, reversible first assignment where possible. Announce the expected access change to affected unit managers, monitor the first real task/session/API request, and have a named owner ready to remove the grant if the boundary is wrong. Do not use a hidden field, a form expression, or a dashboard filter as a substitute for authorization.

## Related guides

* [Roles and scopes](/administration/roles-and-scopes)
* [Public API reference](/reference/public-api)
* [Forms, fields, and repeatables](/build/form-fields-and-repeatables)
* [Public portal](/build/public-portal)
* [KayanOS Automations connections](/build/automations-connections)
* [Troubleshooting](/reference/troubleshooting)