Organizations & Multi-Tenancy

Helix is built from the ground up with multi-tenancy as a core architectural principle, providing strict data isolation and flexible access control.

Hierarchy

Helix organizes content and users in a three-level hierarchy:

Organization
└── Spaces
    └── Branches

Organizations

Organizations are the top-level tenant in Helix. An organization represents a company, team, or project and serves as the primary boundary for data isolation.

  • Each organization has its own members with specific roles
  • All data is strictly isolated by organization via Row-Level Security (RLS)
  • Organizations can have multiple spaces for different projects or environments
  • Access to one organization does not grant access to any other organization

Spaces

Spaces are isolated workspaces within an Organization. Each space contains:

  • Content (entities and their data)
  • Schema definitions (content models)
  • Branches (for content versioning)
  • API keys (for headless access)
  • Settings and configurations

Spaces are accessed via the URL pattern: /s/[org]/[space]

Common use cases for multiple spaces:

  • Environment separation: Production, staging, development spaces
  • Project isolation: Different products or websites
  • Client separation: For agencies managing multiple client projects

Branches

Branches are forks of content within a Space, enabling Git-style workflows. Each space starts with a main branch. See Branching & Merging for details.

Roles & Permissions

Helix provides three built-in roles at the organization level:

Owner

  • Full control over the organization
  • Can delete the organization
  • Can manage all members and their roles
  • Full access to all spaces and their content
  • Can create and delete spaces
  • Can manage billing and subscription settings

Admin

  • Can manage organization members (invite, remove, change roles)
  • Full access to all spaces and their content
  • Can create and delete spaces
  • Can manage space settings and API keys
  • Cannot delete the organization or change the owner

Member

  • Can view and access spaces they're assigned to
  • Can create and edit content within assigned spaces
  • Can create branches and merge content
  • Cannot manage organization members
  • Cannot create or delete spaces
  • Cannot manage billing

Future versions of Helix will support fine-grained, space-level permissions, allowing admins to assign members to specific spaces with custom roles.

Managing Members

Inviting Users

Organization owners and admins can invite new members:

  1. Navigate to Settings → Members in the Admin Studio
  2. Click Invite Member
  3. Enter the user's email address
  4. Select their role (Owner, Admin, or Member)
  5. Click Send Invitation

The invited user will receive an email with a link to accept the invitation and create their account (if they don't have one) or join the organization.

Changing Roles

To change a member's role:

  1. Go to Settings → Members
  2. Find the member in the list
  3. Click the role dropdown next to their name
  4. Select the new role
  5. The change takes effect immediately

To transfer organization ownership, the current owner must promote another member to Owner. There can be multiple owners, but at least one owner must always exist.

Removing Members

To remove a member from the organization:

  1. Navigate to Settings → Members
  2. Find the member you want to remove
  3. Click the Remove button
  4. Confirm the action

Removed members immediately lose access to all spaces within the organization.

Identity & Authentication

Identity

An Identity represents the specific relationship between a User and an Organization. The same user can have different identities (and therefore different roles) across multiple organizations.

For example:

  • Alice is an Owner in "Acme Corp"
  • Alice is a Member in "Consulting Partners"

User Management

Users are managed at the platform level and can belong to multiple organizations. When a user logs in, they select which organization they want to work with.

Authentication is handled via Auth.js and supports:

  • Email/password authentication
  • OAuth providers (Google, GitHub, etc.)
  • Single Sign-On (SSO) for enterprise plans

Row-Level Security (RLS)

Helix enforces multi-tenant isolation at the database level using PostgreSQL Row-Level Security:

  • Every database query automatically includes the organization context
  • Users can only access data belonging to organizations they're a member of
  • Even if a user knows a Space ID or Entity ID from another organization, they cannot access it
  • Database-level isolation prevents accidental data leaks in application code

The RLS context is set using PostgreSQL session variables:

SET app.org_id = 'org_abc123';
SET app.user_id = 'usr_xyz456';

All queries are automatically filtered by these variables, ensuring complete data isolation.

API Keys & Spaces

Each Space can generate its own API keys for headless content delivery:

  • Public API keys: For client-side applications, read-only access
  • Secret API keys: For server-side applications, can include write access if configured

API keys are scoped to a single space and cannot access content from other spaces or organizations.

To create an API key:

  1. Navigate to a Space
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Choose the key type (Public or Secret)
  5. Set permissions (read-only or read-write)
  6. Copy the key (it won't be shown again!)

Never commit API keys to version control. Use environment variables to store keys securely. Rotate keys regularly and immediately revoke any keys that may have been compromised.

Best Practices

Organization Structure

  • Use one organization per company/team
  • Don't create separate organizations for different environments—use Spaces instead
  • Keep organization membership lean—only invite people who need access

Space Organization

  • Use separate spaces for production, staging, and development
  • Consider using spaces for different brands or products within the same organization
  • Use descriptive names: my-brand-production, my-brand-staging

Role Assignment

  • Start with the Member role by default
  • Only promote to Admin if the user needs to manage members or create spaces
  • Limit the number of Owners to reduce security risk
  • Regularly audit member access and remove inactive users

Security

  • Enable two-factor authentication (2FA) for all members
  • Use SSO for organizations with more than 10 members
  • Regularly review and rotate API keys
  • Monitor access logs for suspicious activity