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

# Users and roles

> Invite users, assign roles and branches, and manage access over a person's whole lifecycle.

**Settings → Team / Roles**

Access is granted along three axes — role, module permissions, and branch scope. All three must
line up. This guide covers administering them; see
[Roles and permissions](/getting-started/roles-and-permissions) for how they combine.

## Adding a user

<Steps>
  <Step title="Invite the person">
    **Settings → Team → Add.** Use their work email — it is their identity and where password
    resets go.
  </Step>

  <Step title="Assign a role">
    Administrator, manager, or operator. Start at the least privileged role that lets them do their
    job.
  </Step>

  <Step title="Assign branches">
    Only the branches they work in. Branch scope is a data boundary, not a convenience filter —
    data outside their branches is never returned to them.
  </Step>

  <Step title="Set module permissions">
    The verbs they need: view, create, edit, delete, and module-specific rights such as approve,
    allocate, reverse or assign.
  </Step>

  <Step title="Confirm what they can see">
    Have them sign in and check that the modules they need are present and the ones they should not
    have are absent.
  </Step>
</Steps>

## Roles

| Role                 | Grant it to                                                        |
| -------------------- | ------------------------------------------------------------------ |
| **Super Admin**      | Platform staff only. Cross-organisation tooling.                   |
| **Admin**            | The one or two people who own configuration for the organisation.  |
| **Manager**          | Branch or portfolio leads who approve, assign and read dashboards. |
| **Operator / staff** | Everyone doing day-to-day work.                                    |
| **Resident / Owner** | Portal users. Not operator accounts.                               |

<Warning>
  Administrator is not a seniority marker. It grants control over the chart of accounts, service
  types, settings, feature flags and approval policy — configuration that silently changes what every
  number on the platform means. Keep the count low.
</Warning>

## Separation of duties

Some combinations should not sit with one person:

| Do not combine                                                          | Why                                             |
| ----------------------------------------------------------------------- | ----------------------------------------------- |
| Record an expense **and** approve it                                    | The oldest control in payables.                 |
| Fund an [expense wallet](/guides/expense-wallets) **and** spend from it | The wallet's control value disappears.          |
| Raise a credit note **and** approve it                                  | Uncontrolled revenue reversal.                  |
| Configure a collections strategy **and** approve its demand letters     | No independent check on what reaches residents. |

Where the team is too small to separate them fully, use [approvals](/guides/approvals) so at least
the decision is recorded and visible.

## Changing access

| Situation                 | Action                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| Person changes role       | Update the role and re-check module permissions — they do not follow the role automatically. |
| Person moves branch       | Change branch assignment. Remove the old branch; do not accumulate.                          |
| Person takes on approvals | Grant the approve verb for the relevant modules, and add them as a delegate where required.  |
| Person goes on leave      | Configure an approval delegate, or the approval queue stalls.                                |
| Person leaves             | Deactivate immediately. Do not delete — their audit history must remain attributable.        |

<Warning>
  Deactivate rather than delete. A deleted user breaks the attribution on everything they ever did,
  which undermines the audit trail exactly when you most need it.
</Warning>

## Sessions

**Super Admin → User Sessions → `/user-sessions`** shows active sessions across the platform. Use
it to confirm a departed user is no longer signed in anywhere, and to investigate unexpected
access.

## Reviewing access

<Steps>
  <Step title="Quarterly: review the user list">
    Anyone who has not signed in for a quarter probably does not need access.
  </Step>

  <Step title="Review administrators specifically">
    The list should be short and every name should be justifiable.
  </Step>

  <Step title="Review branch assignments">
    Accumulated branches from old roles are the most common over-permission.
  </Step>

  <Step title="Review approval delegates">
    Delegates set for a holiday two years ago are still delegates.
  </Step>
</Steps>

## Residents and owners

Portal users are not operator accounts. Resident access comes from their
[resident record](/guides/residents) and the units they are associated with; owner access from the
[owner record](/guides/owners-landlords). Granting a resident an operator role gives them
visibility of other people's data.

## Common problems

| Symptom                                         | Cause                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| User cannot see a module                        | Missing permission, or the module's feature flag is off for their branch.    |
| User sees no data at all                        | No branch assigned.                                                          |
| Approvals not reaching anyone                   | No user holds the approve verb for that module, or the approver is inactive. |
| A departed user's name still appears on records | Correct — deactivation preserves history.                                    |