Organizations

OrganizationsService owns Organizations, Memberships, Join Requests, and governance roles. Federation is the authority for these relationships.

An Organization stores no product backend address and owns no product resources. Bureau reads its Bureau URL from trusted product configuration and sends the current user_token to that Bureau. Bureau verifies the user, checks Membership, and applies product resource permissions.

• Client and backend API: Organizations Federation API
• Product backend integration: Integrate Organizations into Bureau

Install

import { Federation } from "@downcity/bureau";
import { OrganizationsService } from "@downcity/services";

const federation = new Federation({ database });

federation.use(new OrganizationsService({
  max_organizations_per_user: 3,
}));

The quota counts every active Organization the user owns across Federation. Archiving releases the slot, and ownership transfer moves it to the new Owner.

Organization scope

Create a Federation-wide Organization:

await bureau.service("organizations").action("create").invoke({
  name: "Genesis Research",
  scope_type: "federation",
});

Create an Organization for the current Bureau:

await bureau.service("organizations").action("create").invoke({
  name: "Genesis Research",
  scope_type: "bureau",
});

Members can access a federation Organization with a token for any Bureau in the same Federation. A bureau Organization requires user_token.bureau_id to equal scope_bureau_id. Federation derives the Bureau scope from the verified token; clients cannot submit or override it.

Federation-wide does not mean public. The service exposes no public search. Products distribute organization_id through invitation links, QR codes, or their own flows.

Membership

A Membership represents one period in which a User belongs to an Organization. Leaving or removal permanently closes that record. Rejoining creates a new membership_id.

await bureau.service("organizations").action("join-requests/create").invoke({
  organization_id: "org_01J...",
});

Owner, Admin, and Member are Organization governance roles. They do not grant editor, viewer, or repository permissions in a product.

Call a product Bureau

Bureau sends the same user_token to the HTTPS Bureau configured by the product:

await bureau.post("https://bureau.example.com/v1/projects", {
  organization_id: "org_01J...",
});

Bureau verifies the token with Federation JWKS and calls membership/get for the current relationship. Organizations Service issues no organization_token and makes no callback to user-controlled URLs.

Databases and archive

The service supports better-sqlite3, PostgreSQL, and Cloudflare D1 through context.transaction(). It contains no database-specific branch.

Archive is terminal. It stops governance writes and releases the Owner quota. Bureau decides what happens to product resources.