Organizations & Teams

The platform uses an organization-based multi-tenancy model for team collaboration and resource isolation. Organizations replace traditional "teams" and provide the primary unit of collaboration, billing, and access control.

Organizations

How Organizations Work

Organizations are the core multi-tenancy boundary in the platform. Every user belongs to an organization, and resources are scoped to the user's organization.

Organization Properties:

• Name and description: Identifies the organization
• Owner: The user who created the organization (has full control)
• Admin IDs: Additional users with administrative privileges
• Billing email: Used for billing notifications and invoices
• Credits: Balance, lifetime usage, enforcement mode, and alert thresholds
• Settings: Timezone, currency, fiscal year start
• Status: Active or inactive

Organization Types

Solo Organizations:

• Created automatically when a user registers in SaaS mode (via password or Google OAuth)
• Named "[User's Name]'s Organization"
• The user is both owner and sole member
• Solo users cannot share resources with others in multi-tenant mode

Team Organizations:

• Created explicitly via the registration flow with users.registerWithNewOrganization
• Support multiple members with different roles
• Members can share resources within the organization

Deployment Modes

The platform supports two independent deployment settings that affect how organizations work:

Setting	Environment Variable	Effect
Multi-tenant mode	SAAS_MODE=true	Enables strict organization-based resource isolation
Billing enabled	BILLING_ENABLED=true	Enables Stripe integration and credit-based billing

These settings are independent -- you can have multi-tenant without billing, or billing without strict multi-tenant isolation.

Single-Tenant Mode (default):

• All users see all other users
• Resources are accessible across users (subject to sharing permissions)
• New users require admin approval before they can log in
• The users.shareable publication returns all users except self

Multi-Tenant Mode (SAAS_MODE=true):

• Users only see other members of their organization
• Resources are filtered by organization using buildResourceAccessQuery()
• New users are auto-activated
• The users.shareable publication returns only organization members
• Solo users cannot share with anyone

Organization Members

Member Roles

Each member has an organization-level role:

Organization Role	Capabilities
Owner	Full control over the organization, billing, and all members
Admin	Manage members and organization settings
Member	Access shared resources within the organization

Organization roles are separate from platform roles (admin, developer, app). A user has both:

• A platform role that determines which UI features they can access
• An organization role that determines their permissions within their organization

Inviting Members

Members are invited to organizations through the invitation system:

1. An existing member (with invite permissions) creates an invitation
2. The invitation is stored in the OrganizationInvitations collection with:
   • Target email address
   • Organization ID
   • Assigned role (owner, admin, member)
   • Invitation token and expiration date
   • Status (pending, accepted, expired)
3. The invited user receives the invitation (via email or shared link)
4. The user registers using users.registerWithInvitation with the invitation token
5. The system verifies:
   • The invitation token is valid and not expired
   • The email matches the invitation email
   • The email is not already registered
6. On success:
   • A new user account is created with the app platform role
   • The user is added to the organization as a member
   • The invitation status is updated to "accepted"
   • A Strongly API key is generated for the user

Member Management

Organization members are tracked in the OrganizationMembers collection:

• organizationId: Which organization the member belongs to
• userId: The user's ID
• role: Organization role (owner, admin, member)
• status: Active or inactive
• invitedBy: Who invited this member
• joinedAt: When the member joined
• artifactsTransferred: Whether resources have been transferred (for offboarding)
• artifactsDeleted: Whether resources have been deleted (for offboarding)

Resource Sharing

How Resource Access Works

In multi-tenant mode, resource access is controlled by the buildResourceAccessQuery() function from the security module. This function:

1. Gets the user's organization context via getUserOrgContext()
2. Builds a MongoDB query that filters resources to only those belonging to the user's organization
3. The query is applied to all resource collections (apps, workflows, data sources, etc.)

Sharing Within an Organization

Within an organization, users can share resources with other members:

• The users.shareable publication returns all active organization members (excluding self)
• The canShareWith() function verifies that the target user is in the same organization
• The validateShareTargets() function filters out invalid share targets
• Shared resources inherit the organization's access boundary

Resource Ownership

Resources in the platform have an owner:

• The owner is the user who created the resource
• Admins can access all resources regardless of ownership
• When a user is archived, their resources remain intact
• Organization-scoped resources persist even if the creating member leaves

User Visibility

Who Can See Whom

User visibility depends on the deployment mode:

Single-Tenant Mode:

• All users can see all other users (via users.basic, users.all, users.shareable publications)
• Admin users can see full user details via users.list publication

Multi-Tenant Mode:

• Users can only see members of their own organization
• Solo users can only see themselves
• The buildUserVisibilityQuery() function restricts user queries to organization members
• Even deprecated publications (users.basic, users.all) are filtered by organization in multi-tenant mode

Best Practices

Organization Structure

• One organization per team or company: Keep related users in the same organization for easy resource sharing
• Use organization roles appropriately: Only grant owner/admin to users who need to manage the organization
• Regular member review: Remove inactive members and review roles periodically

Resource Management

• Ownership clarity: Ensure critical resources are not owned by a single user who might leave
• Naming conventions: Use consistent naming for resources to help organization members find them
• Clean up on departure: When a member leaves, transfer their critical resources before removing them

Security

• Invitation security: Invitation tokens have expiration dates to prevent stale invitations
• Email verification: Invitation emails must match the registered email
• Organization isolation: In multi-tenant mode, resources are strictly isolated between organizations
• Offboarding: Track artifact transfer and deletion status for departing members

Organization vs. Platform Roles

A user's organization role (owner, admin, member) controls their permissions within their organization. Their platform role (admin, developer, app) controls which features they can access in the UI. Both work together to determine overall access.