Organization Units

An organization unit is the type that gives a tenant its internal shape. Where a person or an organization is a participant, a unit is a place: a department, a division, a faculty, a region, a workspace, or any grouping a customer wants to carve their world into. Because a unit is a party like any other, it inherits identity, relationships, ownership, audit, and soft-delete without any special casing, and it adds the few things a structural container needs.

This page assumes the framing in The Party Model. It goes deeper than the type summary in Persons and Organizations because units behave differently from the other types in two important ways: they take part in two separate hierarchies, and they carry configuration that the parties beneath them inherit.

Two Hierarchies, Not One

The single most important thing to understand about units is that there are two distinct hierarchies in play, and they answer different questions.

The first is nesting, which is how units relate to other units. Each unit has an optional parentOuId pointing at the unit it sits inside, so a department sits inside a division, a faculty inside a university, and the units form a tree of their own. A unit with no parent sits directly under the tenant root. This is the hierarchy you walk to answer "what is below this unit" or "what does this unit roll up into."

The second is containment, which is how every other party relates to units. Each party has an organizationUnitId naming the single home unit it lives in, and a null value means it lives at the tenant root. This is a single, indexed reference rather than a relationship, so "everything that lives in this unit" is a direct lookup, and a party lives in exactly one unit at a time.

Keeping these apart matters because they are genuinely different. Nesting is unit-to-unit and forms the organizational skeleton; containment is party-to-unit and places people, services, and organizations onto that skeleton. A faculty nests under a university (nesting), while a student and a case-handling service live in that faculty (containment). The two together let you express both the shape of an organization and where each participant belongs in it.

Containment places a party as a whole in one home unit, but a party that plays several roles can also place each role in its own unit. A role a party bears can name the organization unit that role belongs to, so a person who is a student in one faculty and an employee in another department is a single party whose two roles live in two different units, with one base home unit underneath them. This is how someone wearing several hats sits in several parts of the organization at once without becoming several records. The roles a party plays are covered under Persons and Organizations.

Branding and Terms

Each unit carries the things a part of an organization presents to the people inside it: a terms-of-service URI and a branding configuration, alongside a policy that says how it draws configuration from the units above it. This is what lets a workspace, a faculty, or a regional division look and behave like itself without becoming a separate tenant.

Branding is resolved rather than copied. When the effective branding for a party is needed, the platform starts at the party's home unit and walks up the nesting chain through each parentOuId until it finds a value, so a faculty can override the university's theme for everyone beneath it while a department that sets nothing simply inherits what the faculty, and then the university, provides. Because the value is resolved on read rather than duplicated onto every descendant, changing a unit's branding takes effect for everything below it at once, and there is no stale copy to reconcile. The inheritance policy on a unit governs how much it takes from its ancestors, which is the control point when a unit needs to stop inheriting and stand on its own.

A Unit Is a Full Party

It is worth restating that a unit is not a lightweight grouping bolted onto the side of the model. It is a party, so it has its own identifier, can hold relationships to other parties, can own parties, carries the same audit and soft-delete behaviour as everything else, and can itself be specialized with roles and validated attributes when you need a unit to carry structured properties of its own. A unit is one of the schema-bearing types, alongside persons and organizations, so a profile can give a unit's attributes meaning in the same way it does for a person.

This is also why units are the natural anchor for tenant structure rather than a parallel concept. The same machinery that lists a person's relationships lists a unit's, the same ownership model that ties an identity to a person ties one to a unit, and the same polymorphic read that returns a person returns a unit. You do not learn a second model to work with structure; you use the party model and set partyType to organization_unit.

Groups Within a Unit

A group is the other way to gather parties, and it complements containment rather than competing with it. A group is itself a party, so like every party it has a home organization unit, which means groups are organized per unit: a unit owns its groups the same way it owns the people and services that live in it, and "the groups in this unit" is a direct read off the unit.

What sets a group apart from containment is that its membership is explicit and unrestricted by type. Containment places each party in exactly one home unit and answers "where does this party live." A group, by contrast, is a free-form set you assemble for addressing or authorization, and it can hold any mix of party types at once. A single group can contain people and organizations together, services alongside them, and even other groups nested inside. A data-protection working group in the Legal unit might hold several staff persons, an external auditor organization, and a reporting service as members, all in one group, while each of those members keeps its own separate home unit elsewhere in the tenant.

That freedom is what makes groups useful for authorization. Because a group is a party, it can be the subject or object of relationships, so a rule such as "a member of the group that owns this resource may read it" walks membership the same way any other relationship is walked, which is the relationship-based access described in Relationships. A group carries only a name and its members; it never bears specializations or attributes, which keeps it a pure set. Membership is managed through the group's members sub-resource on the REST API, and because a member can be any party, including another group, you can build nested groupings where that helps.

Working With Units Over REST

Units are created, read, updated, listed, and soft-deleted through /ou exactly like the other typed resources, and they add two reads that reflect the two hierarchies. The children read walks the nesting tree to return the units directly beneath a given unit, and the members read walks containment to return the parties whose home unit is the given one. Both are described, with the rest of the surface, on the REST API page.

A practical pattern for standing up a tenant's structure is to create the top unit first, then create child units that reference it through parentOuId, and finally place people and services by setting their organizationUnitId as you create them. From that point the children and members reads let you navigate the structure in either direction, and branding set high in the tree flows down to everything you placed.