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

# Roles & Permissions

> Understand tenant-wide vs unit-scoped role assignments, how roles cascade through your unit hierarchy, and how to grant the right access to your team.

## Overview

Roles determine what a person can see and do in Kitospace. You assign roles to team
members in two different scopes:

* **Tenant-wide roles** apply everywhere — across every unit in your account.
* **Unit-scoped roles** apply to a single unit (and the units beneath it) only.

The **Roles & Permissions** section on a unit's settings page manages *unit-scoped*
assignments for that specific unit. Tenant-wide assignments are managed from
**Settings → Roles & Permissions**.

## Tenant-Wide vs Unit-Scoped Assignments

|                         | Tenant-wide role               | Unit-scoped role                       |
| ----------------------- | ------------------------------ | -------------------------------------- |
| **Where it applies**    | Every unit in the account      | One unit and its descendants           |
| **Where you assign it** | Settings → Roles & Permissions | The unit's settings page               |
| **Typical use**         | Account administrators, owners | A manager responsible for one property |

Use a tenant-wide role when someone needs access to the whole account. Use a unit-scoped
role when you want to give a person responsibility for one property — a building, a
location, an apartment — without handing them access to everything else.

## Resolution Order

Access for any unit is the **combination** of tenant-wide roles and unit-scoped roles:

1. **Tenant-wide roles apply globally.** They always take effect, on every unit.
2. **Unit-scoped roles extend or narrow access** for specific people on specific units,
   on top of whatever tenant-wide access already exists.

In other words, unit-scoped roles never remove tenant-wide access — they add targeted
access for people who don't have it account-wide.

## Inheritance: How Roles Cascade

Units form a hierarchy: a **domain root** at the top, parent units below it, and child
units beneath those. Role assignments **cascade downward**:

> A role assigned to a parent unit or the domain root applies to **all of its children**.

This means a person assigned a role at **Building A** automatically has that role on
every apartment inside Building A — you don't need to assign it on each child unit.

The unit settings modal shows the effective picture in resolution order:

1. **Domain root** roles first (the top of the hierarchy)
2. **Parent unit** roles next, from the highest ancestor down to the immediate parent
3. **Direct** roles assigned to this unit itself

## Understanding Inherited vs Direct Roles

The **Roles & Permissions** modal separates the two so the source of every role is clear:

* **Inherited Roles** — roles that cascade to this unit from a parent or the domain root.
  They are shown read-only, with a badge naming the source unit. You **cannot revoke an
  inherited role here** — it must be managed from the unit where it was assigned.
* **Direct Assignments** — roles assigned to *this* unit. These can be revoked directly
  from the modal.

When a unit inherits roles from an ancestor, its settings card also shows an
**inheritance summary badge**. If the roles come from a single ancestor, the badge links
straight to that unit's settings so you can manage them at the source.

## Admin Responsibility

Choosing the right role at the unit level is an administrative decision. Keep these
principles in mind:

* **Grant the narrowest scope that still lets the person do their job.** Prefer a
  unit-scoped role over a tenant-wide one when the responsibility is limited to one
  property.
* **Assign at the right level in the hierarchy.** Assigning a role at a parent unit or
  the domain root cascades to every child — convenient, but make sure that breadth is
  intended.
* **Review inherited roles before adding direct ones.** A person may already have the
  access they need through inheritance; a duplicate direct assignment adds clutter.

## Common Use Cases

* **Property manager per unit** — assign a manager role directly on the building (domain
  root or parent unit) so it cascades to every room or apartment inside it.
* **Front desk per location** — assign front-desk staff a unit-scoped role on their
  specific location; they get access to that location's units without seeing other
  properties.
* **Owner with account-wide oversight** — assign a tenant-wide administrator role from
  Settings so the person has visibility across every unit.

## Related

* [Creating & Managing Units](/docs/units/creating-units)