> ## 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.
# Role Based Access Control
> Manage user permissions across your organization, workspaces, and projects.
HoneyHive uses role-based access control (RBAC) to manage permissions across your [organization hierarchy](/v2/workspace/organization-hierarchy). Roles are assigned independently at each scope level -- giving you fine-grained control over who can access and modify resources.
## Key Benefits
* **Scope-level control** -- assign different roles to the same user across different workspaces and projects
* **Least privilege by default** -- members get minimal permissions; admins explicitly grant access
* **Custom role definitions** -- define custom roles with granular permissions (Enterprise plan)
* **Independent scopes** -- permissions at one level do not automatically cascade to child levels
## How Access Is Evaluated
HoneyHive uses a dual-control model to evaluate access. Both conditions must be met for a user to access any workspace, project, or data plane:
1. **Membership** -- the user must be explicitly added to the scope (via invite or auto-assignment).
2. **Role with permissions** -- the user must hold a role that grants the required permissions in that scope.
Neither condition alone is sufficient:
* A user who has been invited to a project but holds no role in it will have no permissions.
* A user who holds a role at a scope level but has not been added to a specific instance of that scope cannot access it.
At login, HoneyHive builds each user's effective permissions by combining their memberships with their role assignments. For each scope where the user has a membership with roles, the platform aggregates the permissions granted by those roles into a consolidated permission set. Permissions are checked on every request.
## Default Roles
HoneyHive ships with default roles at each scope level. Each role defines a set of permissions for that scope.
### Organization Roles
| Role | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Org Admin** | Full control over the organization: manage members, workspaces, roles, API keys, and organization settings. Assigned automatically to the organization creator. |
| **Org Member** | Can view organization members and join workspaces they are invited to. Assigned automatically when a user is invited to the organization or joins via email domain. |
### Workspace Roles
| Role | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace Admin** | Full control over the workspace: manage members, projects, AI provider keys, and workspace settings. Assigned automatically to the workspace creator. |
| **Workspace Member** | Can view workspace projects, create new projects, manage projects they have access to, and use AI provider keys configured in the workspace. Assigned when a user is added to the workspace. |
### Project Roles
| Role | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Project Admin** | Full control over the project: manage members, API keys, datasets, metrics, evaluators, charts, and all project data. Assigned automatically to the project creator. |
| **Project Member** | Can view and create most project resources (traces, datasets, evaluators, experiments, charts) but cannot delete most resources or manage project membership roles. Assigned when a user is added to the project. |
### Data Plane Roles
Data plane roles apply to [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments with [federated architecture](/v2/workspace/organization-hierarchy#federated-deployments).
| Role | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Plane Admin** | Full control over the data plane: manage workspaces, members, API keys, and data plane settings. Assigned automatically to the data plane creator. |
| **Data Plane Member** | Can view data plane members, create workspaces, and list workspaces they belong to. |
## Permission Reference
Every permission in HoneyHive follows the `scope.resource.action` format. For example, `project.dataset.post` allows creating datasets in a project. The tables below list every permission and which default roles include it.
| Permission | Description | Admin | Member |
| ---------------------------------- | -------------------------------------------------------------------------------- | :---: | :----: |
| `org.scope.get` | View organization details | Yes | -- |
| `org.scope.put` | Update organization settings | Yes | -- |
| `org.scope.archive` | Archive the organization | Yes | -- |
| `org.membership.get` | View a member's details | Yes | Yes |
| `org.membership.list` | List all organization members | Yes | Yes |
| `org.membership.add` | Invite a user to the organization | Yes | Yes |
| `org.membership.remove` | Remove a user from the organization | Yes | -- |
| `org.membership.get_roles` | View a member's roles | Yes | -- |
| `org.membership.set_roles` | Change a member's roles | Yes | -- |
| `org.org_api_key.get` | View an organization API key | Yes | -- |
| `org.org_api_key.list` | List organization API keys | Yes | -- |
| `org.org_api_key.post` | Create an organization API key | Yes | -- |
| `org.org_api_key.put` | Update an organization API key | Yes | -- |
| `org.org_api_key.delete` | Delete an organization API key | Yes | -- |
| `org.roles.get` | View role definitions | Yes | -- |
| `org.roles.set` | Create or update role definitions | Yes | -- |
| `org.templates.get` | View organization templates | Yes | -- |
| `org.templates.set` | Update organization templates | Yes | -- |
| `org.dataplane.list` | List all data planes in this organization | Yes | -- |
| `org.dataplane.list_my` | List data planes where you have access | Yes | Yes |
| `org.dataplane.register` | Automatically register a data plane | Yes | Yes |
| `org.dataplane.create` | Manually create a data plane | Yes | -- |
| `org.dataplane.manage_memberships` | Manage members across data planes | Yes | -- |
| `org.analytics.query` | Query organization analytics and view the [Usage](/v2/workspace/usage) dashboard | Yes | -- |
`org.org_api_key.*`, `org.roles.*`, `org.templates.*`, and `org.analytics.*` require the **Enterprise** plan. `org.dataplane.*` permissions apply to [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments with [federated architecture](/v2/workspace/organization-hierarchy#federated-deployments).
Data plane permissions apply to [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments only.
| Permission | Description | Admin | Member |
| ---------------------------------------- | -------------------------------------- | :---: | :----: |
| `dataplane.scope.get` | View data plane details | Yes | -- |
| `dataplane.scope.put` | Update data plane settings | Yes | -- |
| `dataplane.scope.archive` | Archive the data plane | Yes | -- |
| `dataplane.workspace.create` | Create a workspace in this data plane | Yes | Yes |
| `dataplane.workspace.list` | List all workspaces in this data plane | Yes | -- |
| `dataplane.workspace.list_my` | List workspaces you belong to | Yes | Yes |
| `dataplane.workspace.manage_memberships` | Manage members across workspaces | Yes | -- |
| `dataplane.membership.get` | View a member's details | Yes | Yes |
| `dataplane.membership.list` | List all data plane members | Yes | Yes |
| `dataplane.membership.add` | Invite a user to the data plane | Yes | Yes |
| `dataplane.membership.remove` | Remove a user from the data plane | Yes | -- |
| `dataplane.membership.get_roles` | View a member's roles | Yes | -- |
| `dataplane.membership.set_roles` | Change a member's roles | Yes | -- |
| `dataplane.dataplane_api_key.get` | View a data plane API key | Yes | -- |
| `dataplane.dataplane_api_key.list` | List data plane API keys | Yes | -- |
| `dataplane.dataplane_api_key.post` | Create a data plane API key | Yes | -- |
| `dataplane.dataplane_api_key.put` | Update a data plane API key | Yes | -- |
| `dataplane.dataplane_api_key.delete` | Delete a data plane API key | Yes | -- |
| Permission | Description | Admin | Member |
| -------------------------------------- | -------------------------------- | :---: | :----: |
| `workspace.scope.get` | View workspace details | Yes | -- |
| `workspace.scope.put` | Update workspace settings | Yes | -- |
| `workspace.scope.archive` | Archive the workspace | Yes | -- |
| `workspace.project.create` | Create a project | Yes | Yes |
| `workspace.project.list` | List all projects | Yes | -- |
| `workspace.project.list_my` | List projects you belong to | Yes | Yes |
| `workspace.project.put` | Update a project | Yes | Yes |
| `workspace.project.archive` | Archive a project | Yes | Yes |
| `workspace.project.manage_memberships` | Manage members across projects | Yes | -- |
| `workspace.membership.get` | View a member's details | Yes | -- |
| `workspace.membership.list` | List all workspace members | Yes | -- |
| `workspace.membership.add` | Invite a user to the workspace | Yes | Yes |
| `workspace.membership.remove` | Remove a user from the workspace | Yes | -- |
| `workspace.membership.get_roles` | View a member's roles | Yes | -- |
| `workspace.membership.set_roles` | Change a member's roles | Yes | -- |
| `workspace.workspace_api_key.get` | View a workspace API key | Yes | -- |
| `workspace.workspace_api_key.list` | List workspace API keys | Yes | -- |
| `workspace.workspace_api_key.post` | Create a workspace API key | Yes | -- |
| `workspace.workspace_api_key.put` | Update a workspace API key | Yes | -- |
| `workspace.workspace_api_key.delete` | Delete a workspace API key | Yes | -- |
| `workspace.ai_secrets.use` | Use AI provider secrets | Yes | Yes |
| `workspace.ai_secrets.get` | View AI provider secrets | Yes | -- |
| `workspace.ai_secrets.post` | Create an AI provider secret | Yes | -- |
| `workspace.ai_secrets.put` | Update an AI provider secret | Yes | -- |
| `workspace.ai_secrets.delete` | Delete an AI provider secret | Yes | -- |
| `workspace.templates.get` | View workspace templates | Yes | -- |
| `workspace.templates.set` | Update workspace templates | Yes | -- |
| Permission | Description | Admin | Member |
| --------------------------------- | ------------------------------ | :---: | :----: |
| `project.scope.get` | View project details | Yes | -- |
| `project.scope.put` | Update project settings | Yes | -- |
| `project.scope.archive` | Archive the project | Yes | -- |
| `project.membership.get` | View a member's details | Yes | -- |
| `project.membership.list` | List all project members | Yes | Yes |
| `project.membership.add` | Invite a user to the project | Yes | Yes |
| `project.membership.remove` | Remove a user from the project | Yes | -- |
| `project.membership.get_roles` | View a member's roles | Yes | -- |
| `project.membership.set_roles` | Change a member's roles | Yes | -- |
| `project.project_api_key.get` | View a project API key | Yes | Yes |
| `project.project_api_key.list` | List project API keys | Yes | Yes |
| `project.project_api_key.post` | Create a project API key | Yes | Yes |
| `project.project_api_key.put` | Update a project API key | Yes | Yes |
| `project.project_api_key.delete` | Delete a project API key | Yes | -- |
| `project.dataset.get` | View a dataset | Yes | Yes |
| `project.dataset.list` | List datasets | Yes | Yes |
| `project.dataset.post` | Create a dataset | Yes | Yes |
| `project.dataset.put` | Update a dataset | Yes | Yes |
| `project.dataset.delete` | Delete a dataset | Yes | -- |
| `project.datapoint.get` | View a datapoint | Yes | Yes |
| `project.datapoint.list` | List datapoints | Yes | Yes |
| `project.datapoint.post` | Create a datapoint | Yes | Yes |
| `project.datapoint.put` | Update a datapoint | Yes | Yes |
| `project.datapoint.delete` | Delete a datapoint | Yes | -- |
| `project.chart.get` | View a chart | Yes | Yes |
| `project.chart.list` | List charts | Yes | Yes |
| `project.chart.post` | Create a chart | Yes | Yes |
| `project.chart.put` | Update a chart | Yes | Yes |
| `project.chart.delete` | Delete a chart | Yes | -- |
| `project.config.get` | View a configuration | Yes | Yes |
| `project.config.list` | List configurations | Yes | Yes |
| `project.config.post` | Create a configuration | Yes | Yes |
| `project.config.put` | Update a configuration | Yes | Yes |
| `project.config.delete` | Delete a configuration | Yes | -- |
| `project.metric.get` | View a metric | Yes | Yes |
| `project.metric.list` | List metrics | Yes | Yes |
| `project.metric.post` | Create a metric | Yes | Yes |
| `project.metric.put` | Update a metric | Yes | Yes |
| `project.metric.delete` | Delete a metric | Yes | -- |
| `project.experiment_run.get` | View an experiment run | Yes | Yes |
| `project.experiment_run.list` | List experiment runs | Yes | Yes |
| `project.experiment_run.post` | Create an experiment run | Yes | Yes |
| `project.experiment_run.put` | Update an experiment run | Yes | Yes |
| `project.experiment_run.delete` | Delete an experiment run | Yes | -- |
| `project.annotation_queue.get` | View an annotation queue | Yes | Yes |
| `project.annotation_queue.list` | List annotation queues | Yes | Yes |
| `project.annotation_queue.post` | Create an annotation queue | Yes | Yes |
| `project.annotation_queue.put` | Update an annotation queue | Yes | Yes |
| `project.annotation_queue.delete` | Delete an annotation queue | Yes | Yes |
| `project.alert.get` | View an alert | Yes | Yes |
| `project.alert.list` | List alerts | Yes | Yes |
| `project.alert.post` | Create an alert | Yes | Yes |
| `project.alert.put` | Update an alert | Yes | Yes |
| `project.alert.delete` | Delete an alert | Yes | Yes |
| `project.event.get` | View an event | Yes | Yes |
| `project.event.put` | Update an event | Yes | Yes |
| `project.session.get` | View a session | Yes | Yes |
| `project.session.put` | Update a session | Yes | Yes |
| `project.schema.get` | View project schema | Yes | Yes |
| `project.schema.put` | Update project schema | Yes | Yes |
## Custom Roles
Custom role definitions are available on the **Enterprise** plan.
Organizations on the Enterprise plan can define custom roles with granular permission sets. Custom roles let you create permission profiles that match your team's specific access requirements -- for example, a "Reviewer" role that can read project data and annotation queues but cannot modify datasets or metrics.
Custom roles are managed via **Settings > Organization > Roles**. Role definitions apply organization-wide and are available for assignment at any scope level (organization, workspace, or project).
Each custom role specifies:
* The **scope level** it applies to (organization, workspace, or project)
* The **permission set** -- a list of individual permissions the role grants
* **Auto-assignment triggers** -- optional rules for when the role should be automatically assigned (e.g., on workspace creation, on invite)
The platform supports 100+ individual permissions across all scope levels, covering every resource and action in the system.
## Role Assignment
### How roles are assigned
| Trigger | When it fires | Role assigned |
| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **On creation** | User creates an organization, workspace, or project | Admin role for that scope |
| **On invite** | User is invited to a scope | Member role for that scope |
| **Email domain match** | User's email domain matches the organization's verified domain | Org Member (on sign-in) |
| **SAML group claim** | User signs in via SAML SSO with group claims configured | Roles derived from IdP group membership ([details below](#sso-group-based-provisioning)) |
| **Manual** | Admin changes a member's role via **Settings > Members** | Any role available at that scope |
### SSO group-based provisioning
SSO group-based provisioning is available on [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments with SAML SSO configured.
When SAML SSO is configured with group claims, HoneyHive can automatically provision and update user memberships and roles based on the user's IdP group membership. This removes the need for manual invites and role assignments -- access is fully controlled from your identity provider.
Users must already have an organization membership (via email domain match or manual invite) before group-based roles take effect. Group claims control data plane, workspace, and project access -- they do not create organization memberships.
#### How it works
On every sign-in, HoneyHive reads the user's SAML group claims and:
1. **Resets** all SSO-managed data plane, workspace, and project roles to a clean state.
2. **Syncs memberships** -- removes access to data planes no longer declared in the IdP and creates access to newly declared ones.
3. **Assigns roles** based on each group claim, including support for wildcard patterns that apply roles across all workspaces or projects within a scope.
This means **removing a group in your IdP removes the corresponding role on the user's next sign-in.** Access is always kept in sync with your identity provider.
When group-based provisioning is active, **all** data plane, workspace, and project roles are reset on every sign-in -- including any roles that were manually assigned. Manual role changes will not persist across logins. To preserve manual overrides, manage those users outside the SSO group flow.
#### Explicit and wildcard assignments
SAML group claims support two styles of role assignment:
* **Explicit** -- each group claim maps directly to a single scope and role (e.g., a specific workspace or project).
* **Wildcard** -- a single group claim applies a role to all child scopes of a given type. For example, one claim can grant a role across every workspace in a data plane, or every project in a workspace.
Wildcard patterns are useful for broad access policies (e.g., "this user is an admin in all workspaces under data plane X") while explicit claims are used for fine-grained per-scope assignments.
The exact group claim format is configured during your SAML SSO setup. Contact your HoneyHive account team or refer to your deployment's SSO configuration guide for the specific format used in your environment.
#### Important notes
* Group-based provisioning runs on **every sign-in**, ensuring roles always reflect the current IdP state.
* Archived scopes are automatically skipped during provisioning.
### How permissions work across scopes
Permissions are **flat** -- they do not inherit or cascade between scope levels. Each user's effective permissions are computed per scope at login and checked on every request.
**Org Admin does not mean access to all projects.** An Org Admin can manage organization-level settings and members but must be explicitly added to individual workspaces and projects to access their data.
```
Organization (Org Admin)
├── Workspace A (no access -- must be explicitly added)
│ ├── Project 1 (no access)
│ └── Project 2 (no access)
└── Workspace B (Workspace Member -- explicitly added)
├── Project 3 (Project Admin -- explicitly added)
└── Project 4 (no access)
```
This means:
* A user can be a **Workspace Admin** in one workspace and a **Workspace Member** in another.
* A user can be a **Project Admin** in one project and have no access to a different project in the same workspace.
* An **Org Admin** must be added to individual workspaces and projects to access their data.
## Common Scenarios
### Adding a new team member
1. Org Admin invites the user to the organization.
2. User becomes an Org Member.
3. Workspace Admin adds the user to the relevant workspace(s).
4. Project Admin (or Workspace Admin) adds the user to the relevant project(s).
### Creating a new workspace and project
1. Any Org Member creates a new workspace -- they become Workspace Admin automatically.
2. Workspace Admin creates a project -- they become Project Admin automatically.
3. Workspace Admin invites team members to the workspace and assigns them to projects.
### Restricting access within a workspace
A Workspace Admin with multiple projects can control which team members see which projects:
1. Add all team members to the workspace as Workspace Members.
2. Add each member only to the specific projects they need.
3. Members will only see and access projects they have been explicitly added to.
### Offboarding a team member
1. Remove the user from their projects (Project Admin or Workspace Admin).
2. Remove the user from their workspaces (Workspace Admin or Org Admin).
3. Remove the user from the organization (Org Admin) if they are leaving entirely.
## Permission Recipes
These examples show how to achieve common access patterns using custom roles (Enterprise plan) or the default roles.
| Desired behavior | Solution |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| User can only view datasets in a project | Custom role with `project.dataset.get` and `project.dataset.list` |
| User can run experiments but not delete them | Custom role with `project.experiment_run.get`, `.list`, `.post`, `.put` (omit `.delete`) |
| User can manage AI provider secrets but not workspace settings | Custom role with `workspace.ai_secrets.*` (omit `workspace.scope.put`) |
| User can view project data but not modify anything | Custom role with only `.get` and `.list` permissions for the resources they need |
| Workspace admin who cannot archive projects | Custom role with all `workspace.*` permissions except `workspace.project.archive` |
| API-only access for CI/CD pipelines | Use a **project API key** instead of a user role (see below) |
## API Key Permissions
API keys are not user roles -- they have a fixed set of permissions determined by their scope level. They cannot be customized.
Project API keys are the most common type, used for SDK integration and CI/CD pipelines. They can:
| Resource | Permissions |
| ----------------- | -------------------------------------------- |
| Events | `project.event.get`, `project.event.put` |
| Sessions | `project.session.get`, `project.session.put` |
| Datasets | `project.dataset.*` |
| Datapoints | `project.datapoint.*` |
| Metrics | `project.metric.*` |
| Experiment runs | `project.experiment_run.*` |
| Configurations | `project.config.*` |
| Charts | `project.chart.*` |
| Annotation queues | `project.annotation_queue.*` |
| Schema | `project.schema.*` |
Project API keys cannot manage memberships, roles, or other API keys.
| API Key Type | What it can do |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Organization API key** | Manage role definitions (`org.roles.*`), templates (`org.templates.*`), and query analytics (`org.analytics.*`). Requires Enterprise plan. |
| **Workspace API key** | Manage AI provider secrets (`workspace.ai_secrets.*`). |
## Security Guarantees
HoneyHive's RBAC system enforces the following invariants:
* **No privilege escalation** -- users cannot grant themselves roles or expand their own access. Role assignment requires explicit admin permissions (`*.membership.set_roles`) at the relevant scope.
* **No permission inheritance** -- permissions are flat and scoped to each level independently. An Org Admin does not automatically have access to workspaces or projects. A Workspace Admin does not automatically have admin access to projects within that workspace.
* **Cross-scope isolation** -- data queries are always filtered by scope. Traces, datasets, and search results from one workspace or project are never visible to users in another, even within the same organization.
* **Separation of duties** -- in [Dedicated Cloud](/v2/setup/dedicated) and [Self-Hosted](/v2/setup/self-hosted) deployments, platform operators (control plane) cannot access service-domain data (data plane), and service-domain users cannot modify platform or federation configuration. No role combines control plane authority with data plane access.
## FAQ
**Q: Can a user have different roles in different workspaces or projects?**
A: Yes. Roles are assigned independently at each scope. A user can be a Workspace Admin in one workspace and a Workspace Member in another, or a Project Admin in one project and a Project Member in another.
**Q: Can Org Admins access every project automatically?**
A: No. Org Admins can manage organization-level settings and members, but they must be explicitly added to a workspace and project to access data within it.
**Q: Do permissions cascade from organization to workspace to project?**
A: No. Permissions are flat and scoped to each level independently. A Workspace Admin does not automatically have admin access to projects within that workspace.
**Q: Who can create API keys?**
A: API keys are scoped to each level. Org Admins manage organization API keys. Workspace Admins manage workspace API keys. Project Admins and Project Members can manage project API keys.
**Q: Can we define custom roles beyond the six defaults?**
A: Yes, on the Enterprise plan. Navigate to **Settings > Organization > Roles** to define custom roles with granular permissions. The platform supports 100+ individual permissions across all scope levels.
**Q: What happens when a user is invited to the organization?**
A: They receive the Org Member role by default. They will not have access to any workspaces or projects until explicitly added by an admin.
**Q: When do permission changes take effect?**
A: When a user's roles or memberships are updated, their active sessions are marked as stale. The next time the user's browser communicates with the platform, it detects the stale session and triggers a re-authorization to recalculate permissions. The user does not need to log out and log back in. New permissions take effect after the session is re-authorized.
**Q: What if all Org Admins leave?**
A: An Org Admin must promote another user to Org Admin before demoting themselves. If no Org Admin is available, contact [support@honeyhive.ai](mailto:support@honeyhive.ai).