You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Guardian currently provides role-based access control (Standard Registry, User, Auditor, etc.) but lacks an inherent "Organization" level permission abstraction. When another system integrates with Guardian, managing access becomes complex because the external system's organizational hierarchy conflicts with Guardian's flat role-based model. There is no way to group users under an organization entity and manage permissions at that level, which is a common requirement for enterprise integrations.
Apart from the permission levels, another required feature of an Organization entity is that it also has its own Wallet to manage tokens just like Guardian Users.
This feature can improve the quality of life for companies such as Allcot, Xeptagon, and Verra.
After the discussion with hashgraph team, we will be proceeding with Approach 2
Under this approach, an Organization is essentially a Group. Users are included into a group within a policy, and that group represents the organization.
Pros:
Easiest method with minimal development effort.
Does not affect the current Guardian system.
Can include an organization onboarding process inside each policy.
Can set different access levels for each block based on the group (organization) in addition to the usual role-based permissions.
Cons:
Not a proper organizational representation.
Groups are bounded to workflows and cannot be shared across policies. In reality, an organization is an external entity that exists outside of policies/workflows — a single organization may need access to multiple policies.
This does not solve one of the core requirements where an Organization having its own personal wallet to manage tokens.
Suggested improvement for Approach 1: Allow group creation outside of policies (like schemas, roles, and tokens) and enable sharing them among policies. This partially solves the cross-policy limitation, but users would still need to be attached to the relevant group in each policy separately.
Approach 2 (Recommended) — Introduce Organization as a first-class Guardian entity
Similar to how the User concept works in Guardian (users onboard to the Guardian instance rather than to individual policies), an Organization entity would be introduced at the Guardian platform level with a clear relationship to users (1-to-Many or Many-to-Many).
Pros:
Clean alignment with the general User-Organization mapping used by external systems.
A user's organization(s) are attached at the Guardian level and accessible uniformly across all policies (no per-policy organization onboarding).
Block access can be configured in a clearer, more human-readable manner.
Can introduce Organizational wallet features.
In both Indexer and Sustainability explorer, it will be possible to map the Projects to their own Organizations (as requested by most of the stakeholders) and provide filters accordingly.
Cons:
Higher complexity and broader impact on the current Guardian system.
Requires not only the User-Organization mapping but also reworking the in-policy block access mechanism to support organizational access control.
User Roles within policies may need re-evaluation if organizations have their own access levels (admin, read, write, etc.).
All API access levels and user role permissions within Guardian (policy edit, policy read, etc.) must be re-evaluated with organizational constraints.
Requirements
Introduce an "Organization" entity at the Guardian platform level (Approach 2), not bounded to individual policies.
Support User-Organization relationships as 1-to-Many or Many-to-Many (a user can belong to one or more organizations; an organization has multiple users).
Organization membership must be accessible uniformly across all policies — policies should not control organization onboarding.
Rework the in-policy block access mechanism to support organization-based access control alongside existing role-based permissions.
Re-evaluate existing User Roles within policies to accommodate organization-level access levels (e.g., org-admin, org-read, org-write).
Re-evaluate all API access levels and user role permissions (policy edit, policy read, etc.) with organizational constraints.
Provide API endpoints for CRUD operations on organizations and user-organization assignments.
External systems should be able to manage user access at the organization level through the API.
As a transitional step, consider the Approach 1 improvement (allowing group creation outside of policies and sharing across policies) as an interim solution if the full Approach 2 implementation timeline is extended.
Definition of done
An Organization entity exists in Guardian at the platform level (not policy-scoped) with a clear many-to-many relationship to users.
API endpoints allow creation, management, and querying of organizations and their user memberships.
Labels:
enhancement,api,access-control,medium-priorityProblem description
Guardian currently provides role-based access control (Standard Registry, User, Auditor, etc.) but lacks an inherent "Organization" level permission abstraction. When another system integrates with Guardian, managing access becomes complex because the external system's organizational hierarchy conflicts with Guardian's flat role-based model. There is no way to group users under an organization entity and manage permissions at that level, which is a common requirement for enterprise integrations.
Apart from the permission levels, another required feature of an Organization entity is that it also has its own Wallet to manage tokens just like Guardian Users.
This feature can improve the quality of life for companies such as Allcot, Xeptagon, and Verra.
After the discussion with hashgraph team, we will be proceeding with Approach 2
Analysis of implementation approaches
Two approaches have been evaluated:
Approach 1 — Wrap organization concept around Guardian's existing "Group" entity
Under this approach, an Organization is essentially a Group. Users are included into a group within a policy, and that group represents the organization.
Pros:
Easiest method with minimal development effort.
Does not affect the current Guardian system.
Can include an organization onboarding process inside each policy.
Can set different access levels for each block based on the group (organization) in addition to the usual role-based permissions.
Cons:
Not a proper organizational representation.
Groups are bounded to workflows and cannot be shared across policies. In reality, an organization is an external entity that exists outside of policies/workflows — a single organization may need access to multiple policies.
This does not solve one of the core requirements where an Organization having its own personal wallet to manage tokens.
Suggested improvement for Approach 1: Allow group creation outside of policies (like schemas, roles, and tokens) and enable sharing them among policies. This partially solves the cross-policy limitation, but users would still need to be attached to the relevant group in each policy separately.
Approach 2 (Recommended) — Introduce Organization as a first-class Guardian entity
Similar to how the User concept works in Guardian (users onboard to the Guardian instance rather than to individual policies), an Organization entity would be introduced at the Guardian platform level with a clear relationship to users (1-to-Many or Many-to-Many).
Pros:
Clean alignment with the general User-Organization mapping used by external systems.
A user's organization(s) are attached at the Guardian level and accessible uniformly across all policies (no per-policy organization onboarding).
Block access can be configured in a clearer, more human-readable manner.
Can introduce Organizational wallet features.
In both Indexer and Sustainability explorer, it will be possible to map the Projects to their own Organizations (as requested by most of the stakeholders) and provide filters accordingly.
Cons:
Higher complexity and broader impact on the current Guardian system.
Requires not only the User-Organization mapping but also reworking the in-policy block access mechanism to support organizational access control.
User Roles within policies may need re-evaluation if organizations have their own access levels (admin, read, write, etc.).
All API access levels and user role permissions within Guardian (policy edit, policy read, etc.) must be re-evaluated with organizational constraints.
Requirements
Introduce an "Organization" entity at the Guardian platform level (Approach 2), not bounded to individual policies.
Support User-Organization relationships as 1-to-Many or Many-to-Many (a user can belong to one or more organizations; an organization has multiple users).
Organization membership must be accessible uniformly across all policies — policies should not control organization onboarding.
Rework the in-policy block access mechanism to support organization-based access control alongside existing role-based permissions.
Re-evaluate existing User Roles within policies to accommodate organization-level access levels (e.g., org-admin, org-read, org-write).
Re-evaluate all API access levels and user role permissions (policy edit, policy read, etc.) with organizational constraints.
Provide API endpoints for CRUD operations on organizations and user-organization assignments.
External systems should be able to manage user access at the organization level through the API.
As a transitional step, consider the Approach 1 improvement (allowing group creation outside of policies and sharing across policies) as an interim solution if the full Approach 2 implementation timeline is extended.
Definition of done
An Organization entity exists in Guardian at the platform level (not policy-scoped) with a clear many-to-many relationship to users.
API endpoints allow creation, management, and querying of organizations and their user memberships.
In-policy block access supports organization-based permissions alongside role-based permissions.
All existing API access levels and role permissions have been reviewed and updated to incorporate organizational constraints.
External systems can map their organizational hierarchies to Guardian organizations for unified access management.
Acceptance criteria
An Organization entity can be created, read, updated, and deleted via API at the Guardian platform level (not per-policy).
Users can be assigned to and removed from organizations via API, supporting many-to-many relationships.
A user's organization membership is accessible uniformly across all policies without per-policy onboarding.
Policy block access can be configured based on organization membership in addition to role-based permissions.
Organization-level access levels (e.g., admin, read, write) are supported and configurable.
Existing role-based permissions continue to work unchanged for backward compatibility.
All API access levels and user role permissions (policy edit, policy read, etc.) enforce organizational constraints where configured.
The organization-user mapping is queryable (list users in an organization, list organizations for a user).
API documentation covers all organization-related endpoints, access control changes, and migration guidance.
External systems can integrate with the organization model to manage access hierarchically.