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

# Roles and permissions

> How access is granted in Nyumba Zetu — roles, module permissions, branch scope, and approvals.

Access in Nyumba Zetu is decided by three independent things. All three must line up before you
can do something.

<Steps>
  <Step title="Your role">
    Broad identity: super administrator, administrator, manager, operator, or resident.
  </Step>

  <Step title="Your module permissions">
    Fine-grained rights per module — view, create, edit, delete, and module-specific verbs such as
    *approve*, *allocate*, *reverse*, *assign* or *generate*.
  </Step>

  <Step title="Your branch scope">
    Which branches you may work in. Data outside your branches is not filtered out of your view —
    it is not returned to you at all.
  </Step>
</Steps>

## Roles

| Role                 | Typical use                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Super Admin**      | Platform staff. Cross-organisation tooling: companies, properties, user sessions, platform health, analytics.             |
| **Admin**            | Organisation administrator. Configures settings, service types, chart of accounts, users, roles, strategies and policies. |
| **Manager**          | Runs a branch or portfolio. Approves, assigns work, sees dashboards and reports.                                          |
| **Operator / staff** | Day-to-day work: create leases and invoices, receive payments, work a collections queue, log interactions.                |
| **Resident**         | Tenant-portal user. Sees only their own units, leases, bills and requests.                                                |
| **Owner**            | Landlord. Sees their own units, statements, fees and disbursements.                                                       |

<Note>
  A person can hold more than one resident-side role. Owner and tenant are recorded per unit, so the
  same individual can be a tenant in one unit and the owner of another.
</Note>

## Module permissions

Permissions are grouped by module and follow a consistent verb pattern. The modules that carry
their own permission sets are:

<Columns cols={3}>
  <Card title="Core records">
    Users · Properties · Units · Tenants · Landlords · Employees · Lease Agreements ·
    KYC Documents
  </Card>

  <Card title="Money">
    Finance · Invoices · Payments · Expenses · Vendors · Banks · Budget · Credit Notes ·
    Refunds · Chart of Accounts · eTIMS
  </Card>

  <Card title="Operations">
    Maintenance · Service Requests · Utilities · Visitors · Documents · Notice Board · Polls ·
    Requisitions · Tasks · Sales · Chat · Mailbox · Reports · Dashboard · Activity Logs
  </Card>
</Columns>

Beyond the standard **view / create / edit / delete**, some modules add verbs that matter
operationally:

| Verb       | Where it appears          | What it gates                                          |
| ---------- | ------------------------- | ------------------------------------------------------ |
| `approve`  | Finance                   | Approving invoices, expenses and other routed actions. |
| `generate` | Finance, Reports          | Running generation jobs and producing report output.   |
| `allocate` | Refunds, Payments         | Applying money against debt.                           |
| `reverse`  | Refunds                   | Undoing an allocation or refund.                       |
| `assign`   | Service Requests, Tasks   | Handing work to another user.                          |
| `complete` | Tasks                     | Closing work items.                                    |
| `download` | Reports, Lease Agreements | Exporting data and documents.                          |

## What you see when you lack a permission

* **The menu item is absent.** Navigation is filtered by permission — a missing item means no
  right, not a broken build.
* **The action button is disabled** with a reason on hover, when the page itself is visible but a
  specific action is not available to you.
* **A page returns "not authorised"** if you navigate directly to a URL you cannot access.

## Separation of duties: approvals

Some actions are deliberately *not* granted to one person end to end. Instead they route to the
[approvals inbox](/guides/approvals), where a second person with the right role decides. Typical
routed actions:

* Issuing an invoice above a threshold
* Paying an expense
* Issuing a demand letter, handing a case over, or waiving a fee
* Writing off debt or closing a case with a write-off
* Publishing a message template or broadcast

The approval decision — and the reason given — is recorded on the record's timeline.

## Everything is audited

Console mutations are written to an append-only audit trail with the actor, the entity, the
action, the before/after values and, where the action requires it, a mandatory reason. Job-driven
changes are recorded the same way with the job as the actor, so a system-made change is never
indistinguishable from a human one. See [Activity log](/guides/activity-log).

## Administering access

Administrators manage users, roles and branch assignments under **Settings → Team / Roles**. See
[Users and roles](/guides/users-and-roles) for the full workflow, including inviting users,
changing a role, restricting a user to specific branches, and deactivating someone who leaves.