#Organizations

alepha/api/organizations provides organizations, members, ownership, ranks, and invitations as one coherent boundary.

1import { AlephaApiOrganizations } from "alepha/api/organizations";

The module owns four related rows:

• an organization with a name, optional slug, logo, and metadata;
• a membership that links one user to one organization and carries a rank;
• a rank definition scoped to one organization;
• an invitation addressed to an email address and scoped to one organization.

Keeping these together matters. Membership is the authority row used by resource authorization, the rank is stored on that same row, and accepting an invitation creates that row. There is one owner rank and every organization is created with an owner membership.

#Organizations and members

OrganizationController provides create, list, read, update, and delete actions under /organizations. MemberController lists and removes members (/organizations/:organizationId/members) and owns the explicit leave and ownership transfer actions. There is no "add member" endpoint: a member joins by accepting an invitation, and assigning a rank belongs to OrganizationRankController (see Ranks). Server code can call MemberService.add() directly.

AdminOrganizationController (/admin/organizations, gated by admin:organization:read, :update, :delete) and AdminOrganizationInvitationController (/admin/organization-invitations, admin:invitation:read) serve the back office.

Ownership is transferred, never assigned as an ordinary rank. The transfer updates the old and new owner together, so an organization is not left with zero or two owners. The owner cannot leave or be removed until ownership has been transferred.

Applications can narrow creation, deletion, capacity, and refusal policy by substituting OrganizationPolicyProvider:

 1import { OrganizationPolicyProvider } from "alepha/api/organizations"; 2  3class AppOrganizationPolicy extends OrganizationPolicyProvider { 4  public override async assertRoom(organizationId: string): Promise<void> { 5    // Apply the application's subscription or seat policy here. 6  } 7} 8  9alepha.with({10  provide: OrganizationPolicyProvider,11  use: AppOrganizationPolicy,12});

The provider also exposes assertCanCreate, assertCanDelete, ownedBy, and refuse. The module supplies permissive defaults except for the structural membership, owner, and rank invariants.

#Resource authorization

Use $ownsOrganization when a route is directly scoped to an organization:

 1read = $action({ 2  method: "GET", 3  path: "/organizations/:organizationId/report", 4  use: [ 5    $ownsOrganization({ 6      param: "organizationId", 7      requires: "report:read", 8    }), 9  ],10  handler: () => this.report.read(),11});

The primitive is $owns configured with organization_members. It checks membership and hands requires to the module's RankGrantsProvider. Application permission and organization rank permission are both required.

For a resource whose route names an application row rather than the organization, pass its repository and use key to identify the organization column on the authority row:

1$ownsOrganization({2  repository: () => this.projects,3  param: "projectId",4  key: "organizationId",5  requires: "project:update",6});

Here $owns loads the project, then matches memberships with project.organizationId. A missing or null key fails closed. through is also available for routes whose row belongs to another authority row.

$ownsOrganization also passes from, resolve, secure, cache and message straight to $owns (see Resource Authorization). It has no owner option: membership is the whole answer, and the owner is simply the member holding the owner rank. The default denial message is Not a member of this organization.

#Ranks

A rank answers what somebody may do inside one organization. Roles remain application-wide; ranks vary by organization for the same user.

The module creates two built-ins:

• owner, which grants * and cannot be edited or assigned;
• member, which starts from organizationConfigAtom.memberPermissions and can be customized.

Anything else is a custom rank the owner creates. The module seeds none: an organization starts with these two, and @alepha/ui's OrganizationRanks editor offers a blank rank plus whatever presets the application passes it (Lore's Admin, Contributor and Viewer), each saved as an ordinary custom rank under a fresh key.

The effective set includes organizationConfigAtom.floor. Permissions in ownerOnly can never be granted to another rank. A writer also cannot grant a permission they do not hold, change their own assignment, remove a rank that somebody holds, or edit their rank into a self-lockout.

Rank definitions are cached. Assignments are not: the membership row is read for each authorization decision, so a demotion or removal applies on the next request.

OrganizationRankController provides the permission catalogue, rank list, save, delete, and assignment actions under /organizations/:organizationId/ranks. These actions use the same policy as the authorization gate, so a custom editor cannot bypass the module's invariants.

#Invitations

An organization invitation is keyed by email rather than user ID, so it can address someone who has no account without creating a placeholder user. Its status moves from pending to accepted, declined, expired, or revoked.

OrganizationInvitationController creates, lists and revokes invitations under /organizations/:organizationId/invitations, and serves the recipient's side under /organizations/invitations: me (my pending invitations), preview, and :invitationId/accept / :invitationId/decline.

Creating an invitation checks the inviter's rank, validates the target rank, checks organization capacity through OrganizationPolicyProvider.assertRoom, and enforces the configured pending caps. Acceptance checks capacity again, because two pending invitations may race for the last seat.

The organization:invitation:created hook carries the one-time token. Send it using the application's own mail and registration URL:

 1$hook({ 2  on: "organization:invitation:created", 3  handler: async ({ invitation, token }) => { 4    await this.mail.push({ 5      contact: invitation.email, 6      variables: { 7        url: `${base}/auth/register?invitation=${encodeURIComponent(token)}`, 8      }, 9    });10  },11});

The module emits a hook at every step: organization:invitation:created, :accepted, :declined, :expired and :revoked, plus organization:member:removed (with leave: true when the member left) and organization:ownership:transferred.

The token is valid only while the invitation is pending, unexpired, and bound to the registering email address. Revocation changes status instead of deleting the row, preserving the audit trail until the purge job removes old resolved invitations.

#Closed-realm signup

An invitation can admit its recipient while ordinary registration stays closed. Connect the module's InvitationRegistrationService to $realm:

1realm = $realm({2  settings: { registrationAllowed: false },3  isPreAuthorized: (context) =>4    this.alepha.inject(InvitationRegistrationService).preAuthorize(context),5});

A credentials registration must present the token. A verified OAuth address can use its pending invitation because the token does not survive the provider round trip. A valid token proves the email address and avoids sending a second verification message.

#Configuration and jobs

organizationConfigAtom configures:

OrganizationInvitationJobs expires overdue invitations (system.organization-invitations.expire) and purges old resolved rows (system.organization-invitations.purge-resolved), both hourly. Set invitationPurgeDays to 0 to keep the audit rows indefinitely.

Registering the module substitutes RankGrantsProvider for ResourceGrantsProvider, so every requires in the application becomes rank-aware. It must be registered before the classes whose $owns gates use requires; the wrong order throws at boot.

#See also

• Resource Authorization
• Authentication