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

# Legal entities

> Multiple Rechtsträger inside one installation — when you need them and how scoping works.

An installation is one customer. But a customer may employ people through **more than
one legal employer** — a foundation and an operating company, several school
corporations under one umbrella. Swiss HR Easy models these as **legal entities**
(Rechtsträger) inside a single tenant, rather than as separate installations.

This is [ADR-010](/development/adr).

## Why it matters

The legal entity is not a reporting label. It is the **employer of record**, and it
routes every statutory declaration:

* AHV/ALV contributions and the AHV-Lohnbescheinigung
* Quellensteuer settlement and the QST-Bescheinigung
* BVG and the other social-insurance contracts
* The Lohnausweis and the Swissdec ELM Jahresmeldung

Move a person to a different entity and every one of those changes destination.

## Off by default

Unlike every other module flag, `multi-legal-entity` ships **disabled**. A
single-employer installation keeps one invisible default entity and never sees the
entity-management UI at all. Turn it on per installation with
`FEATURE_MULTI_LEGAL_ENTITY=true`.

<Note>
  Enabling the flag does not migrate anything. Existing records stay on the default entity until you
  deliberately assign them.
</Note>

## Permissions

| Capability                       | Role        | Why                                                                                                                           |
| -------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `legal-entity:view`              | `HR_STAFF`+ | HR needs to see which employer a person sits under.                                                                           |
| `legal-entity:manage`            | `ADMIN`+    | The entity record drives every payroll declaration.                                                                           |
| `legal-entity:transfer-employee` | `ADMIN`+    | Transfers and in-place corrections re-route AHV, QST, BVG, EMA and the Lohnausweis. One tier above ordinary `employees:edit`. |

## Read scope vs. write scope

This distinction matters if you are building on the platform.

* **Reads** may use the ambient resolver, `getCurrentLegalEntityId()`. It answers
  "which entity is this user currently looking at?".
* **Writes** must never use it. Every write persists an **explicit, tenant-validated**
  `legalEntityId`, resolved through `resolveWriteLegalEntity` from the legal-entity
  module contract (or an equivalent tenant-scoped, active-entity lookup).

The reason is concrete: the ambient resolver is on a path to becoming
cookie-driven. Stamping a write with its value would let a user-controlled cookie
decide who legally employs a person.

<Warning>
  `getCurrentLegalEntityId()` is read-scope only. Using it on a write path is a security defect, not
  a style preference.
</Warning>

## Rolling out entities on a live installation

There is a dedicated operations playbook for turning a single-employer installation
into a multi-entity one — it covers the ordering of entity creation, employee
assignment, and the payroll cut-over. See
[Runbooks](/operations/runbooks).