Organizations API

Organizations API

OrganizationsService manages private organizations, active membership, governance roles, and join requests. Only active members can read private details and member lists. Owners/admins can edit names and join policy and review requests. Archiving, transferring the sole owner, and managing admin roles remain owner-only operations.

const organizations = federation.user.service("organizations");
const created = await organizations.action("create").invoke({ name: "Research" });
const organization_id = created.organization.organization_id;
// Owners/admins explicitly allow new requests, which still require review.
await organizations.action("update").invoke({ organization_id, join_policy: "approval" });
const mine = await organizations.get("my");

join_policy is closed or approval; new organizations default to closed. Closing new requests preserves pending requests: applicants can cancel their own, and owners/admins can still review them. Once open, signed-in users with an organization ID can call join-requests/create. This grants no access to private details or members. The service provides no public discovery, generic invitations, or webhook authorization.

GET /v1/organizations/my, get, membership/get, and members/list read data available to the authenticated user. POST create, update, archive, members/role, members/remove, members/leave, owner/transfer, and join-requests/* perform domain operations. GET uses query parameters and POST uses JSON; identity comes from the User Token, never a self-reported user input.

await organizations.action("join-requests/create").invoke({ organization_id });
await organizations.action("join-requests/decide").invoke({ request_id, decision: "approved" });

A user can access joined organizations from different Cities. city_id only records source; it never affects membership, management permissions, or owner quota. Active owner quota is global within Federation. Archiving releases quota; ownership transfer checks the recipient's quota. Services that own documents or projects enforce their own resource permissions using authenticated users and active membership.