> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization Hierarchy

> Understand how organizations, workspaces, and projects structure your HoneyHive account and control access to traces, datasets, evaluators, and provider keys.

HoneyHive organizes your account into three levels: **Organization**, **Workspace**, and **Project**. Each level controls different aspects of access, configuration, and data isolation.

<Info>
  New organizations are provisioned with a default workspace and project so you can start tracing without creating every scope by hand. You can rename, archive, or add more workspaces and projects later as your team grows.
</Info>

```mermaid theme={null}
    sequenceDiagram
        participant Org as Organization
        participant WS as Workspace
        participant Proj as Project

        Note over Org: Manage Roles, Scopes, Memberships, Templates, Billing, and Feature Flags.
        Org->>WS: Create per team, BU, or department
        Note over WS: Manage Projects, AI Secrets, and Memberships
        WS->>Proj: Create per AI application or agent
        Note over Proj: All Core Features, Memberships, and API Keys
```

## Organization

An organization is the top-level entity in HoneyHive. It represents your company or team and serves as the boundary for billing, SSO configuration, and organization-wide settings.

* Users are members of one or more organizations.
* SSO and SAML providers are configured at the organization level.
* Organization admins manage members, workspaces, [role definitions](/v2/workspace/roles), and [templates](/v2/workspace/templates).
* Custom role definitions are configured per-organization via **Settings > Organization > Roles** (Teams and Enterprise plans).

## Workspace

A workspace is a team boundary within your organization. Use workspaces to separate teams, departments, or business units that need independent access controls and configurations.

Each workspace has its own:

* **Members and roles** -- control who can access the workspace and its projects
* **AI provider keys** -- configure API keys for LLM evaluators and the Playground (see [Provider Keys](/v2/workspace/provider-keys))
* **API keys** -- issue [fine-grained API keys](/v2/workspace/api-keys) that manage the workspace and the projects inside it
* **Projects** -- each workspace contains one or more projects

Workspaces are useful when different teams within your organization need:

* Separate access controls (e.g., the ML platform team vs. the product team)
* Different AI provider configurations (e.g., one team uses Azure OpenAI, another uses AWS Bedrock)
* Clear data boundaries between teams

<Info>
  For smaller teams, a single workspace with multiple projects is a common setup. You can always add more workspaces as your organization grows.
</Info>

## Project

A project is the boundary for a single AI application or agent. All observability and evaluation data lives within a project:

* **Traces and spans** -- runtime telemetry from your application
* **Datasets and datapoints** -- test data for offline evaluation
* **Experiments** -- evaluation runs comparing model performance
* **Metrics and evaluators** -- quality scoring definitions
* **Prompts** -- managed prompt templates and versions
* **Charts and dashboards** -- monitoring views

Each project has its own [API key](/v2/workspace/api-keys) for SDK authentication. When you instrument your application with the HoneyHive SDK, traces are routed to the project associated with your API key.

For guidance on organizing projects within a workspace, see [Managing Projects](/v2/workspace/projects).

## Self-Hosted Deployments

<Info>
  The additional scope levels described in this section apply to [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments only. Multi-Tenant SaaS customers use the three-level hierarchy described above.
</Info>

Dedicated Cloud and Self-Hosted deployments extend the hierarchy with three additional scope levels to support physical data isolation across multiple clusters or cloud accounts:

```mermaid theme={null}
graph TD
  SYS["System<br/><i>Bootstrap</i>"]
  CP["Control Plane<br/><i>Cluster Management & Telemetry</i>"]
  Org["Organization<br/><i>Administration</i>"]
  DP1["Data Plane A<br/><i>Physical PII Isolation</i>"]
  DP2["Data Plane B<br/><i>Physical PII Isolation</i>"]
  WS1["Workspace 1"]
  WS2["Workspace 2"]
  WS3["Workspace 3"]
  P1["Project 1"]
  P2["Project 2"]
  P3["Project 3"]

  SYS --> CP
  CP --> Org
  Org --> DP1
  Org --> DP2
  DP1 --> WS1
  DP1 --> WS2
  DP2 --> WS3
  WS1 --> P1
  WS1 --> P2
  WS3 --> P3

  classDef selfhosted stroke:#8899bb,stroke-dasharray:5
  class SYS,CP,DP1,DP2 selfhosted
```

### System

The system scope exists for one-time platform bootstrap during initial deployment. It is used only during federation initialization and is not accessible during normal operation.

### Control Plane

The control plane scope manages organization creation and federation configuration. It handles authentication, RBAC policy, and organizational metadata. The control plane has no access to service-domain data stored in data planes.

### Data Plane

A data plane is a **physical isolation boundary** for data and PII. Each data plane is hosted on a dedicated infrastructure cluster, ensuring that application data (traces, evaluations, datasets) from one data plane is isolated from another.

Data planes sit between the organization and workspace levels. Within a data plane, workspaces and projects function exactly as described above -- the data plane adds a layer of physical infrastructure isolation on top of the logical team isolation that workspaces provide.

* Data plane admins can create and manage workspaces within their data plane.
* Data plane admins cannot access organization-level configuration or other data planes.
* Users in one data plane cannot see or query data from another data plane.

<Tip>
  On deployments with SAML SSO and group claims configured, data plane, workspace, and project access can be automatically provisioned based on the user's IdP groups. See [SSO group-based provisioning](/v2/workspace/roles#sso-group-based-provisioning) for details.
</Tip>

For more on how control planes and data planes interact, see [Platform Architecture](/v2/platform-architecture).

## When to use workspaces vs. projects

| Scenario                                            | Recommendation                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------- |
| One team, multiple AI applications                  | One workspace, one project per application                          |
| Multiple teams, each with their own apps            | One workspace per team, projects within each                        |
| Shared platform team serving multiple product teams | One workspace per product team, platform team members added to each |
| Strict data isolation between business units        | Separate workspaces per unit                                        |

## Access control

Roles are assigned at each level of the hierarchy independently. A user can be an admin in one workspace and a regular member in another. Administrative permissions (`*.scope.*` and `*.membership.*`) cascade downward from parent-scope admin roles, so an Org Admin or Workspace Admin can manage settings and members on descendant scopes without a separate admin role on each one. Data permissions do not cascade -- users must be explicitly added to a project to access its data.

See [Role Based Access Control](/v2/workspace/roles) for the full list of roles and permissions at each level.


## Related topics

- [API Keys](/v2/workspace/api-keys.md)
- [Inviting Teammates](/v2/workspace/inviting-teammates.md)
- [Role Based Access Control](/v2/workspace/roles.md)