Roles and Permission Scope

OpenFactory stores independent roles at the organization, unit, and team levels. A role name describes a scope; it is not a universal permission that automatically applies to every API or product feature.

Scope Model


organization membership: owner | admin | member
└── unit membership: unit_admin | base_creator | base_approver | member
    └── team membership: team_lead | variant_creator | variant_deployer | variant_user

Organization membership is the outer boundary. A user must be an organization member before an administrator can add them to one of its units or teams. Membership is checked independently at each level; do not infer a unit or team role from an organization role shown in another context.

Organization Roles

The current organization-management API enforces these permissions:

Operation	Owner	Admin	Member
View organization, members, groups, units, and teams	Yes	Yes	Yes
Edit organization name or description	Yes	Yes	No
Create, edit, or delete groups and manage group members	Yes	Yes	No
Invite or remove ordinary members	Yes	Yes	No
Change ordinary member/admin roles	Yes	Yes	No
Invite or promote an owner	Yes	No	No
Change or remove an existing owner	Yes	No	No
Create or delete units	Yes	Yes	No
Delete the organization	Yes	No	No
Leave the organization	Yes, unless the only owner	Yes	Yes

An organization can have more than one owner. The API prevents the sole owner from leaving until another owner exists or the organization is deleted. There is no separate “transfer ownership” action in this API; an owner changes another member’s role to owner, then may change or remove the prior owner as intended.

Unit Roles

Organization owners and admins can manage every unit. Within a unit, the current organization-management API grants unit_admin the following administrative operations:

edit the unit;
add, remove, and change unit-member roles;
create, edit, and delete teams in that unit;
add and manage team members in that unit.

Only an organization owner or admin can delete the unit itself.

base_creator, base_approver, and unit member are stored role labels for base-image workflow policy. The organization CRUD routes do not themselves prove that every create, approve, or deployment action elsewhere enforces those labels. Verify the authorization behavior of the specific build or approval workflow before relying on it as a control.

Team Roles

Organization owners/admins and the parent unit’s unit_admin can manage team membership. A team_lead can:

edit the team’s name or description;
add and remove team members;
change team-member roles.

A team_lead cannot delete the team through the current organization API; that operation is reserved for an organization owner/admin or parent unit_admin.

variant_creator, variant_deployer, and variant_user express the intended variant-workflow responsibilities. They should not be read as proof that every variant endpoint enforces a complete create/edit/deploy matrix. Test the exact workflow and denied paths in the deployed release.

Groups Are Different

Groups are organization-level sharing collections, not another role hierarchy. Owners and admins create groups and manage group membership; all organization members can list groups and their members. A group membership does not turn a user into an organization admin, unit admin, or team lead.

Changing a Role Safely

Confirm the target organization, unit, or team.
Record the user’s current effective memberships at all three scopes.
Apply one role change.
Test both an allowed operation and a denied operation with that user’s own session.
Check that cached UI state and existing sessions reflect the change.
Retain an audit record outside the role label if your policy requires one.

Changing a label without a denied-path test is not sufficient evidence that least privilege is enforced.

Common Edge Cases

An admin cannot promote anyone to owner or change an existing owner’s role.
A user cannot be added to a unit or team until they belong to the organization.
Unit and team members may remove themselves; organization membership remains unless separately removed.
Removing organization membership should be checked for stale unit, team, group, share, and session effects in your release.
UI badge colors are presentation, not a security control. Always rely on server-side authorization and denied-path tests.