Organizations

Some customers are bigger than one workspace. A company runs a workspace per country, a partner manages workspaces for its clients, a group admin needs one dashboard over every team. An organization is an optional level above workspaces for them: it groups workspaces, and its members get a role there that also lets them into all or some of its workspaces, without a membership in each one.

Organizations are off by default and change nothing until you turn them on. Workspaces keep working on their own, and a workspace belongs to at most one organization.

Turning them on

Featureworkspace Organizations are part of WorkspaceModule. Turn them on in the workspace section:

[workspace.organizations]
enabled = true
resolvers = ["header", "path", "subdomain", "claim"]  # tried in order
header = "X-Organization"
# base_domain = "partners.example.com"   # acme.partners.example.com names `acme`
path_prefix = "/o"                       # /api/o/acme/... names `acme`
claim = "organization"                   # a claim of the bearer JWT

[workspace.organizations.roles.admin]
permissions = ["reports.read"]

From the environment: APP_WORKSPACE__ORGANIZATIONS__ENABLED=true, APP_WORKSPACE__ORGANIZATIONS__RESOLVERS=subdomain,header. While enabled is false, the organization routes aren't mounted, workspace resolution ignores organizations, and the services answer a 500 that names the setting (workspace.organizations.enabled is false: turn it on to use this in the log).

The workspace migration set creates the organization tables whether the feature is on or not, so turning it on later needs no migration:

It also adds workspaces.organization_id, the organization a workspace is attached to.

Creating organizations

The Organizations service creates organizations and attaches workspaces to them. As with the workspace services, writes take the unit of work to run in, go through Repo and emit their events once it commits:

use navree::workspace::{NewOrganization, Organizations};

let acme = organizations
    .create(
        &uow,
        user_id,
        NewOrganization::named("Acme Group").country("gb").timezone("Europe/London"),
    )
    .await?;
assert_eq!(acme.slug, "acme-group");
assert_eq!(acme.country.as_deref(), Some("GB"));

organizations.attach(&uow, acme.id, uk_workspace.id).await?;
organizations.attach(&uow, acme.id, de_workspace.id).await?;

The creator becomes the owner, with the owner role and every workspace. Slugs follow the workspace rules (Acme Group becomes acme-group, then acme-group-2; or set one with .slug("acme")). country is an ISO 3166-1 alpha-2 code, stored in upper case; timezone is an IANA name such as Europe/London, stored under its current name (Asia/Calcutta is stored as Asia/Kolkata). An unknown zone or country is a 400 on that field. The organization's zone is the zone of its workspaces that have none of their own: see time zones.

Organization roles

Each member has one OrgRole. It gives permissions inside the organization and maps to the workspace role the member has in the workspaces they reach:

Add permissions to a role, change the workspace role it gives, or define your own role under workspace.organizations.roles:

[workspace.roles.auditor]                     # a workspace role
permissions = ["workspace.read", "deals.read"]

[workspace.organizations.roles.member]
permissions = ["reports.read"]
workspace_role = "viewer"                      # organization members only read in workspaces

[workspace.organizations.roles.partner]       # an app-defined organization role
permissions = ["organization.read", "reports.read"]
workspace_role = "auditor"

workspace_role defaults to the workspace role of the same name, which must exist: a role named partner without workspace_role needs a workspace.roles.partner. A name that is neither fails the boot. The permissions use the module's subjects:

Members and the workspaces they reach

OrgMembers adds members with a role and a WorkspaceSelector: All of the organization's workspaces, including ones attached later, or Only the listed ones:

use navree::workspace::{OrgMembers, OrgRole, WorkspaceSelector};

// Grace runs every workspace of the organization.
org_members.add(&uow, acme.id, grace, OrgRole::Admin, WorkspaceSelector::All).await?;
// Linus works in the UK workspace only.
org_members
    .add(&uow, acme.id, linus, OrgRole::Member, WorkspaceSelector::only([uk_workspace.id]))
    .await?;
// Add, or change a member's role and workspaces.
org_members
    .grant(&uow, acme.id, linus, OrgRole::Viewer, WorkspaceSelector::All)
    .await?;

list returns each member with their workspaces and, when the user directory knows them, their name and email. The owner (organizations.owner_id) always has the owner role and every workspace: removing, demoting or limiting them is a 409, The organization owner can't be removed, demoted or limited; transfer ownership first.

In JSON a selector is "all" or an array of workspace ids, in the routes and in events.

Entering workspaces through the organization

With organizations on, workspace resolution admits a user who is a member of the workspace, or a member of its organization whose selector includes it. An organization member enters with the workspace role their organization role gives, so behind InWorkspace the route's #[roles], #[permissions] and #[can] checks see that role, and nothing in your workspace routes changes.

A membership of the workspace wins over the organization grant. CurrentWorkspace::granted_by() tells the two apart:

use navree::workspace::GrantedBy;

match ws.granted_by() {
    GrantedBy::Membership => { /* a row of workspace_members */ }
    GrantedBy::Organization { organization_id, role } => {
        // entered as `role` of `organization_id`; ws.role() is the mapped workspace role
    }
}

Workspaces::for_user and GET /api/workspaces list the workspaces a user reaches through organizations next to their own, and Workspaces::role_of(workspace, user) returns the role and how it was granted. A user who enters through an organization has no workspace_members row: ws.member() carries their organization membership's id and dates with the mapped role, and the workspace's member list doesn't show them.

The current organization

Organization-level routes (a dashboard over every workspace, the organization's settings) take a CurrentOrganization. It resolves the organization from the request, loads it and checks that the signed-in user is a member:

They work as the workspace resolvers do, with their own settings, so a request can name a workspace and an organization at once. Put the InOrganization guard on the controller so the route's checks run against the organization role:

use navree::db::paginate;
use navree::prelude::*;

use crate::deals::entity::{Deal, deal};

#[injectable]
pub struct ReportsController;

#[controller("/reports", version = "1")]
#[guard(InOrganization::guard())]
impl ReportsController {
    #[get("/deals")]
    #[permissions("reports.read")]
    async fn deals(&self, org: CurrentOrganization, uow: Uow, page: PageQuery) -> Result<Page<deal::Model>> {
        // Every deal of the workspaces this member reaches.
        let select = OrgRepo::<Deal>::select(org.workspace_ids());
        Ok(paginate(select, &*uow.tx().await?, page).await?)
    }
}

InOrganization::from_path("organization") reads a route's path parameter instead; the built-in /api/organizations/{organization}/... routes use it.

Inside an organization request, navree-access builds the abilities from your abilities function with the organization role: ctx.user.roles holds the organization role, ctx.permissions its permissions, ctx.team_id is None and ctx.organization_id is Some(organization id). Inside a workspace request, ctx.organization_id is the workspace's organization, if it has one.

Reading across workspaces

OrgRepo<E> reads a workspace-scoped entity across several workspaces: every query filters the workspace column by the ids you pass, usually org.workspace_ids(). An empty list matches nothing.

OrgRepo only reads. Writes go to one workspace at a time, through WorkspaceRepo inside a workspace request. It reads row isolation's shared tables; schema and database isolation keep each workspace's rows apart physically.

On PostgreSQL, an organization request sets navree.organization for its transaction. A row-level security policy built with RlsPolicy::new("deals").organizations() lets it read the rows of every workspace attached to the organization, and still writes only with navree.workspace set (see data isolation). The policy sees the whole organization; OrgRepo with workspace_ids() narrows a member limited to Only some workspaces. Jobs scope a unit of work with organizations.enter(&uow, id).

Access requests

A user who isn't a member can ask to join, for the whole organization or one of its workspaces. Admins (organization.access_requests.*) approve, which makes them a member, or decline:

use navree::workspace::{AccessRequests, Approval, NewAccessRequest, OrgRole};

let request = access_requests
    .request(
        &uow,
        acme.id,
        ken,
        NewAccessRequest { workspace_id: Some(uk_workspace.id), message: Some("I run the UK team".into()) },
    )
    .await?;

// Ken joins as a member of the workspace he asked for.
let approved = access_requests
    .approve(&uow, acme.id, request.id, Some(grace), Approval::default())
    .await?;
assert_eq!(approved.member.user_id, ken);

• A user has at most one pending request per organization: a second one is a 409, An access request is already pending., and so is a request from a member.
• Approval { role, workspaces } defaults to member, reaching the workspace the request named, or every workspace when it named none.
• decline(&uow, org, id, decided_by, reason) records an optional reason (up to 1,000 characters, as the message).
• Deciding a decided request is a 409; an unknown one a 404.
• pending(org) lists the pending requests with the users' names and emails; for_user(user) lists a user's requests.

The module tells no one by itself. Listen to AccessRequested to notify the admins.

The routes

With workspace.routes and workspace.organizations.enabled on, the module mounts these routes under the API prefix. {organization} is a slug or an id, and every route needs a signed-in user:

An admin limited to some workspaces grants only workspaces they reach and changes only members whose workspaces they reach: anything else is a 403, You can only grant workspaces you reach. (code workspace_grant_forbidden). Attaching a workspace takes its owner: an organization admin can't pull in a workspace that isn't theirs (a 403, not_the_workspace_owner). An organization comes back as:

{
  "__type": "Organization",
  "id": "0199f3c2-7a1b-7c2d-8e3f-4a5b6c7d8e9f",
  "name": "Acme Group",
  "slug": "acme-group",
  "owner_id": "0199f3c2-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "country": "GB",
  "timezone": "Europe/London",
  "role": "admin",
  "workspaces": "all",
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z"
}

Workspaces in every response carry organization_id (null for a standalone workspace). The routes are in the OpenAPI document under the Organizations tag.

Events

Each event is emitted once its unit of work commits. They live in navree::workspace::events:

Testing

Turn the feature on in the test app's configuration, then check that each member sees what their grant allows:

let app = TestApp::builder()
    .temp_database()
    .config("workspace.organizations.enabled", true)
    // ... modules
    .build()
    .await;

let admin = app.acting_as(principal(ada));
admin.post("/api/organizations").json(&json!({ "name": "Acme" })).send().await.assert_status(201);
admin
    .post("/api/organizations/acme/workspaces")
    .json(&json!({ "workspace": "acme-uk" }))
    .send()
    .await
    .assert_status(200);
admin
    .post("/api/organizations/acme/members")
    .json(&json!({ "user_id": linus, "role": "member", "workspaces": [uk.id] }))
    .send()
    .await
    .assert_status(201);

let member = app.acting_as(principal(linus));
member
    .get("/api/v1/deals")
    .header("X-Workspace", "acme-uk") // reached through the organization
    .send()
    .await
    .assert_status(200);
member
    .get("/api/v1/deals")
    .header("X-Workspace", "acme-de") // not in Linus's selector
    .send()
    .await
    .assert_error(403, "You are not a member of this workspace.");