Skip to main content
HoneyHive uses role-based access control (RBAC) to manage permissions across your 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
  • Permission inheritance — admin roles can perform basic management tasks (editing settings, managing members) across all descendant scopes.
  • Custom role definitions — define custom roles with granular permissions (Enterprise plan)

​
How Access Is Evaluated

HoneyHive uses a dual-control model to evaluate data access. Both conditions must be met for a user to view or modify project data (traces, datasets, evaluators, and similar resources):
  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.
Administrative permissions (*.scope.* and *.membership.*) from parent-scope admin roles inherit downward to descendant scopes without requiring membership on each child. See Permission inheritance. 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

​
Workspace Roles

​
Project Roles

​
Data Plane Roles

Data plane roles apply to Dedicated Cloud and Self-Hosted deployments with federated architecture.

​
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.
org.org_api_key.*, org.roles.*, org.templates.*, and org.analytics.* require the Enterprise plan. org.dataplane.* permissions apply to Dedicated Cloud and Self-Hosted deployments with federated architecture.
Data plane permissions apply to Dedicated Cloud and Self-Hosted deployments only.

​
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

​
SSO group-based provisioning

SSO group-based provisioning is available on Dedicated Cloud and 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.

​
Permission Inheritance

​
Downward permission inheritance migration

In v1.3.0, child-scope list and manage_memberships permissions remain accepted for compatibility but are deprecated for custom admin roles. Replace them with descendant *.scope.* and *.membership.* permissions before a future removal.
The optional permissions let higher-level admins manage deeper descendants directly. For example, add project.scope.* and project.membership.* to DataPlaneAdmin if data plane admins should manage project settings and project members without an explicit workspace-level role. Parent-scope admin roles cascade *.scope.* and *.membership.* permissions to descendant scopes. Org Admin cascades through data planes, workspaces, and projects; Data Plane Admin cascades through workspaces and projects; Workspace Admin cascades through projects in that workspace. Org Admin does not mean access to all project data. An Org Admin can manage settings and members on descendant scopes but must be explicitly added to a project with a data-granting role to access its traces, datasets, and similar resources.
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 projects to access project data.
The base HoneyHive Cloud plan uses default member and admin role definitions that include permission inheritance. Self-hosted deployments can add custom roles with custom permission sets to match their needs.

​
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.

​
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:Project API keys cannot manage memberships, roles, or other API keys.

​
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.
  • Permission inheritance — only *.scope.* and *.membership.* permissions can cascade from a parent-scope role to its descendants; data permissions never inherit. For example, an Org Admin can manage members in every project in the org but cannot read that project’s traces without a data-granting role assigned on the project itself.
  • 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 and 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: For management, yes. For data, no. Admins inherit *.scope.* and *.membership.* permissions on all descendant scopes (data planes, workspaces, and projects), so they can manage settings and members without a separate admin role on each one. They do not inherit access to project data (traces, datasets, evaluators, and similar resources) - that requires being explicitly added to the project with a data-granting role. Q: Do permissions cascade from organization to workspace to project? A: Only administrative permissions cascade. *.scope.* and *.membership.* permissions from parent-scope admin roles expand to descendant scopes at login. Data permissions never cascade — a Workspace Admin cannot view traces in a project unless they hold a data-granting role on that project. 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.