Organizations and Spaces

The Bivariant platform uses organizations and spaces to provide multi-tenant data isolation, access control, and project separation.

The platform is multi-tenant by design. Organizations and spaces form the hierarchy that controls data isolation, access, and resource scoping.

Organizations

An organization is the top-level tenant boundary. All resources on the platform — apps, collections, conversations, connections, and users — belong to an organization.

Organizations provide:

Data isolation — an organization's data is never accessible to another organization
User management — accounts are added as members with assigned roles
Resource ownership — all platform resources are scoped to an organization
Billing boundary — usage and subscriptions are tracked per organization

Every account starts with a default organization created during signup. Accounts can belong to multiple organizations.

Organization members

Users access an organization by being added as members. Each membership includes:

Account — the user identity
Role — the set of permissions granted (for example, admin, member, or a custom role)
Status — active, invited, or suspended

Service accounts (used by apps and agents) are also organization members, typically with the member role.

Spaces

A space is an isolated environment within an organization. Spaces allow teams to separate projects, departments, or deployment stages within the same organization.

Apps are installed into spaces. Data within a space (conversations, collections, configurations) is scoped to that space.

Common uses for spaces:

Project separation — different products or initiatives in separate spaces
Team isolation — marketing, support, and engineering each with their own space
Environment staging — development, staging, and production as different spaces

Each organization starts with a default space. Additional spaces can be created as needed.

Spaces have a productKind that determines their purpose and available features. For example, a space of type presence is configured for the embeddable widget experience, with channels, agents, and brand settings.

Accounts

An account represents an individual identity on the platform. There are two types:

Type	Description
User account	A human user who interacts with the platform through the UI or API
Service account	An automated identity created for apps and agents to execute operations and participate in conversations

Accounts are managed through the platform's identity provider (Zitadel). Each account has:

A unique identifier
A display name and optional avatar
Email and authentication credentials (for human users)
Organization memberships with roles

Service accounts

When an app is installed, the platform creates service accounts for:

The app itself — used for system-level operations on behalf of the app
Each agent — used when agents participate in conversations and execute actions

These service accounts are added as members of the organization, allowing them to operate within the platform's permission system.

Access control hierarchy

Organization
├── Members (accounts + roles)
├── Groups (optional groupings of members)
└── Spaces
    └── Apps (installed blueprints)
        ├── App service account
        └── Agent service accounts

Permissions are checked at the organization level. Roles define what operations a member can perform. See Roles and Permissions for details.

Authentication — how users authenticate and obtain access tokens
Roles and Permissions — configuring access control
Apps — how applications are installed within spaces
Build-time vs. Runtime — how organization scoping affects data isolation