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 for every self-registered user (via password or Google OAuth)
• The user is both owner and sole member
• Solo users cannot share resources with others in multi-tenant mode

Team Organizations:

• Created explicitly through the register-with-new-organization flow
• Support multiple members with different roles
• Members can share resources within the organization

Deployment Modes

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

Setting	Environment Variable	Effect
Multi-tenant mode	MULTI_TENANT=true	Enables strict organization-based resource isolation and user visibility
SaaS mode	SAAS_MODE=true	Self-registered users are auto-activated instead of waiting for admin approval
Billing enabled	BILLING_ENABLED=true	Enables credit-based billing

These settings are independent -- you can have multi-tenant isolation 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 self-registered users require admin approval before they can log in (unless SaaS mode is on)
• The users.shareable publication returns all users except self

Multi-Tenant Mode (MULTI_TENANT=true):

• Users only see other members of their organization
• Resources are filtered by organization
• 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
Viewer	Read-only access to 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 with:
   • Target email address
   • Organization ID
   • Assigned role (admin, member, or viewer)
   • Invitation token and expiration date
   • Status (pending, accepted, expired, or revoked)
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 with the invitation's role
   • The invitation status is updated to "accepted"

Member Management

Each organization member record tracks:

• Which organization the member belongs to
• The member's organization role (owner, admin, member, viewer)
• Membership status (active, pending, suspended, or removed)
• Who invited the member and when they joined
• Whether the member's resources have been transferred or deleted (for offboarding)

Resource Sharing

How Resource Access Works

In multi-tenant mode, every resource query is filtered to the user's organization. This applies to all resource types (apps, workflows, data sources, etc.), so members of one organization never see another organization's resources.

Sharing Within an Organization

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

• The share picker lists all active organization members (excluding yourself)
• Share targets are verified to be in the same organization; targets outside it are rejected
• 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
• Admin users can additionally see full user details

Multi-Tenant Mode:

• Users can only see members of their own organization
• Solo users can only see themselves

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, viewer) 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.