> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Permissions Migration > Distinguish today's additive group permissions from the future authorization migration and stage a safe cutover. OpenCore is introducing permission grants on groups while retaining existing role and object-scope checks. Treat this as an additive migration with a mixed enforcement period, not as a completed role replacement. **Version status:** The current source includes phase-one backend group grants, but the Groups UI labels the rollout **Upcoming** and does not expose permission toggles. Curator and Global Curator remain active and tested. Do not remove or demote those roles based on this page. Any future role retirement is a migration target only; verify the running release, UI, API, and endpoint coverage before cutover. ## Version status matrix | Area | Current status | Migration implication | | ------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Group permission storage | Direct grants and recomputed effective permissions exist in the backend | Grants can be staged without assuming every endpoint consumes them. | | Group administration API | Admin-only read and update operations exist for toggleable permissions | API availability does not prove that the deployed UI exposes the controls. | | Groups UI | Shows an upcoming-permissions notice and manages membership and shared resources | Admins need version-specific tooling before using group grants as an operational control. | | Curator roles | Curator and Global Curator dependencies, scope checks, and tests remain active | Preserve role assignments throughout the mixed-enforcement period. | | Full permission migration | Future target; no source-backed removal version is defined | Plan the cutover only after the running release proves complete coverage. | ## Current authorization model | Layer | Current behavior | Boundary to verify | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Request permission guard | Permission-aware endpoints require a named effective permission; personal access token scopes are checked as an additional restriction | Test both the user session and any token used for the same operation. | | Group grants | A user's effective permissions are recomputed from the union of direct grants on their groups | Membership or grant changes must be followed by effective-permission verification. | | Implied permissions | Broader write permissions imply related read permissions at evaluation time | Store only direct grants and verify the effective result instead of duplicating implied grants. | | Role and object scope | Admin, Curator, Global Curator, ownership, and group-resource checks still protect legacy or scoped operations | A group grant does not automatically bypass an existing role or ownership check. | Basic access, administrative override, internal implied permissions, and protected service behavior are not toggleable group grants. The backend rejects attempts to grant non-toggleable permissions through the group permission API. ## Current Groups workflow #### Create and name the group An Admin creates the group. The backend assigns basic access to a new group and recomputes member permissions when membership or grants change. #### Manage members and shared resources The current Groups UI can update the group name, members, connector or credential-pair scope, and shared Agent or document-set relationships when those features are available. #### Preserve role scope Curators continue to operate only within the group and object scopes allowed by their current role. Global Curators continue to use their current member-group scope. #### Use permission APIs only with version evidence The backend permission read and update routes require full Admin access and accept only toggleable permissions. Confirm that the running deployment includes those routes before using them outside a test environment. The current UI does not provide a permission-toggle control. A successful group edit in that UI therefore verifies membership or resource sharing, not a permission grant. ## Current role behavior | Role | Current authority | Migration rule | | -------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Admin | Deployment-wide configuration and Admin-only group permission routes | Retain an emergency Admin path throughout migration. | | Curator | Scoped management for groups for which the person is a curator | Preserve until every delegated operation has an equivalent tested permission path. | | Global Curator | Scoped management for member groups under the current role rules | Preserve until member-group behavior has an equivalent tested permission path. | | User | Basic use plus resources and operations made available by existing shares and effective permissions | Test representative users instead of inferring access from group membership alone. | Curator removal is not a current capability or completed source change. Existing Curator flows and scope boundaries remain part of the running authorization contract. ## Future migration target The target below is a plan, not a statement of current availability. Do not schedule role retirement until the deployed product exposes the required group controls and the relevant endpoints consistently enforce the new permission model. | Target | Completion evidence | | ------------------------------- | --------------------------------------------------------------------------------------------------------- | | Administrable group grants | Admins can view and change supported grants through approved tooling in the running release. | | Consistent endpoint enforcement | Each migrated endpoint checks the intended permission, token scope, tenant, ownership, and object scope. | | Delegation parity | Every required Curator workflow has a tested replacement without broadening resource access. | | Observable rollback | Grant changes, effective permissions, denials, and retained role assignments can be audited and reversed. | ## Migration runbook #### Inventory current authority Export or record Admin, Curator, Global Curator, group membership, shared-resource, ownership, and token-scope assignments. Map each operational task to its current endpoint and object boundary. #### Confirm the running version Verify that the deployed backend provides the intended group permission routes and that approved administration tooling exposes the grants. Keep role assignments unchanged. #### Stage additive grants Add the minimum toggleable grants to controlled groups. Re-read each affected user's effective permissions and record the expected implied permissions. #### Test every path Use representative users and personal access tokens to test allowed and denied operations, tenant boundaries, ownership rules, and group-resource scope. Include legacy Curator workflows in the regression set. #### Cut over only after parity Change a role assignment only after all required paths have equivalent tested coverage, operational owners approve the result, and rollback data is available. Make changes in small cohorts. ## Verification matrix | Scenario | Expected result | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | Member with a staged direct grant | The intended operation succeeds and the related implied read permission is visible when applicable. | | Member after grant revocation | Effective permissions are recomputed and the protected operation is denied. | | Token without the required scope | The operation is denied even when the user's session permissions would allow it. | | User outside the tenant, group, ownership, or resource scope | The operation remains denied despite an unrelated permission grant. | | Existing Curator during mixed enforcement | Current scoped workflows continue to work and do not expand beyond their tested group or ownership boundary. | ## Rollback Keep the pre-migration role and membership inventory until every cohort is stable. If a grant path is missing, over-broad, or inconsistent, revoke the staged grant, recompute and verify effective permissions, restore any changed role assignment, and retest the legacy path. Do not use role deletion as a rollback mechanism. ## Related pages * [Users, Groups & Roles](/opencore/governance/users-and-groups) describes the current role and sharing boundaries. * [Usage, Identity & Security](/opencore/governance/usage-and-security) covers authentication and security controls that can condition access. * [Data Flows](/opencore/governance/data-flows) explains where tenant and ACL filters enter retrieval.