Permissions & Roles

Albumi’s access model answers one question for every action: can this user do this thing to this entity? The answer is computed from three independent signals, never from one alone.

canDo(user, action, entity) = f(workspace role, ownership of this entity, grant on this entity)

The three signals do different jobs. The workspace role says what kind of member the user is across the whole workspace. Ownership says who is accountable for one specific entity. Grants attach extra rights on top — either to one entity, or to all entities of a given type. None of these dimensions is collapsed into the others, and organizational classification is not one of them.

The rest of this page goes through each dimension, the separation between direct editing and proposing, the cases where the rules bend (Initiatives, the root Organization, Architecture Change Requests), and how multi-workspace membership works. For the change workflow that sits on top of all of this, see Governance Overview.

The workspace and why it scopes everything

A workspace is Albumi’s tenant boundary: one landscape, one set of users, one set of governance rules. Every entity, every comment, every change request lives inside exactly one workspace. Every request a user makes is scoped to one workspace at a time — that is the context in which the access model is evaluated.

Role is per-user per workspace. The same person can be an Admin in the workspace where they are the enterprise architect, a Contributor in the workspace where they review a partner’s landscape, and a Viewer in a third where they only consume dashboards. None of those memberships sees the others — switching workspace is a deliberate act that rebinds the user’s role to the one the new workspace has granted them.

Without a workspace context, no data is visible at all. Users who belong to multiple workspaces pick one when they sign in and switch explicitly; automated clients pass the workspace along with each request.

Dimension 1 — Workspace role

Every member of a workspace has exactly one of three roles in that workspace.

• Admin — the superset. An Admin can do everything in that workspace: read, create, edit directly, propose, comment, approve, reject, implement, archive, delete. Admins own governance (create and manage review boards), member management, and any action that other roles cannot take. Admin is the only role that can approve a change without further constraint and the only role that can directly edit an entity they do not own. Use it sparingly — one or two people per workspace is usually correct.

• Contributor — the working role for people who shape the landscape. A Contributor reads everything in the workspace. They can create entities of the types their role covers, own entities and edit those directly, propose changes on any entity they do not own, comment on entities and change requests, and participate in review sessions they have been added to. A Contributor cannot edit an entity they do not own, cannot delete an entity they do not own, cannot manage workspace members, and cannot create review boards.

• Viewer — read-only. A Viewer sees the landscape, dashboards, change requests, and review sessions, but cannot create, edit, propose, or comment. Viewers exist for stakeholders who need visibility without being able to introduce data.

The role is the coarse filter. Everything else — ownership, grants, the proposal path — only matters above the Viewer line.

Contributor role scoping by entity type

A workspace Contributor’s role can be scoped to specific entity types. A “full-landscape” Contributor has rights across every entity type; a scoped Contributor only has them for the types their grant names — for example, only Applications and Integrations.

The scope affects two things: which types the Contributor can create, and which types they pick up a “workspace-wide Contributor” footing on when they are not the owner. A Contributor who is scoped to Applications and Integrations can create Applications and Integrations, can comment on any entity of those types, and can propose changes on any Application or Integration. On IT Components, Data Objects, or Business Capabilities they fall back to Viewer rights on entities they neither own nor have an entity-level grant for.

Scoping is a tool for larger workspaces where responsibility is divided — the data team edits Data Objects, the application portfolio team edits Applications. In smaller workspaces, leave the Contributor role broad.

Dimension 2 — Ownership of an entity

Every content entity — Application, Integration, Data Object, Business Capability, IT Component, Organization, Initiative, Album — has an ownerUser field that names the single accountable person. Ownership is a property of the entity, set on the entity itself, and transferable at any time to another user in the same workspace (by the current owner or by an Admin).

Ownership exists to answer “who edits this directly?”.

• Owners can directly edit their entity. No proposal. No review. The change becomes current state as soon as they save it.
• Owners can archive, reactivate, delete, and manage per-entity grants on the entity they own.
• Owners are automatically allowed to comment on their entity and on any change request that touches it.

Ownership is narrower than role: an Admin can directly edit any entity regardless of who owns it, but a Contributor without ownership cannot directly edit anything — even entities they created. The creator of an entity becomes its owner by default; reassigning ownership is how a Contributor relinquishes that right.

Ownership is nullable on most entity types — an entity may sit without an owner while accountability is being decided. While the owner is unset, only Admins can edit the entity directly; everyone else is on the proposal path. Assigning an owner is normally the first thing to do after creating an entity, precisely so that direct edits are not bottlenecked on Admin time.

Dimension 3 — Entity-level grants

An owner (or an Admin) can grant Contributor rights on one specific entity to another user. The grant is attached to that one entity and affects only that entity. It is how you bring a named collaborator into the edit conversation without making them an owner and without widening their workspace role.

An entity-level grant widens two surfaces on that entity:

• Propose a change. The grantee can file change proposals on that entity even if their workspace role would otherwise not cover its type.
• Comment. The grantee can comment on the entity and on change requests that touch it.

Crucially, an entity-level grant does not unlock direct editing of the entity. It does not turn the grantee into a co-owner. It does not allow them to delete the entity, to archive it, to transfer ownership, or to manage grants on it themselves. Those remain owner-and-Admin actions. If you intend for someone to edit the entity directly, transfer ownership to them — do not try to reproduce that through a grant.

Grants accumulate. A user can hold grants on many entities; each grant affects only the entity it is attached to.

Direct edit vs propose — the fundamental separation

Almost every confusion about permissions in Albumi comes down to this distinction, so it gets its own section.

Direct edit changes the landscape immediately. The entity’s fields are updated, activity is logged, and the new values are current state as soon as the save returns. Direct edit is an owner-only action (Admin counts as honorary owner of everything). No Contributor role, no entity-level grant, no workspace-wide type scope unlocks direct editing of an entity you do not own.

Proposing a change opens a draft edit against the same entity, grouped under a Change Request. The proposal is reviewed and approved before it becomes current state. Proposing is the path available to Contributors who are not the owner — whether their Contributor footing comes from a workspace-wide type grant or an entity-level grant. See Change Requests for how proposals move through draft, submitted, approved, and implemented.

A way to read the model: ownership buys you speed; Contributor rights buy you a seat at the table. If you want to edit without review, you must own the entity. If you want to shape an entity you do not own, you propose.

One more consequence worth stating plainly: deletion follows the same rule as direct edit. Only the owner and Admins can delete an entity. A Contributor with an entity-level grant or a workspace-wide type scope cannot delete — they can only propose changes. Deletion itself is still gated by referential integrity: an entity that is referenced elsewhere cannot be deleted until those references are removed, independent of who is trying to delete it.

Organization is not a permission dimension

This is the single most frequent mistake. The Organizations concept page states it from the entity side; the authorization side states it here.

An entity’s organization field names the unit of the business the entity is classified under. It is used for filtering, roll-ups, and portfolio views. It is not used to decide access. Users do not inherit rights on an entity because they sit in the same Organization that the entity is classified under. There is no “Finance users automatically edit Finance applications” mechanism, by design.

If you want a specific group of users to be able to edit a specific set of entities, the tools are: name one of them as ownerUser, and grant entity-level Contributor rights to the others. Alternatively, widen their workspace Contributor scope to the entity type. Do not reach for Organization — it will not do what you hope.

Worked examples

Each example names the user’s workspace role, whether they own the entity, and whether they hold an entity-level grant. The result is what the product allows.

1. Admin edits an Application they did not create. Role: Admin. Ownership: no. Grant: none. Result: direct edit allowed. Admin is the superset; no further conditions apply.

2. A Contributor edits an Application they do not own. Role: Contributor (scope includes Applications). Ownership: no. Grant: none. Result: direct edit denied. Propose-change allowed. Comment allowed. The Contributor’s workspace scope says they can work with Applications, but working with one they do not own means proposing the change.

3. An Application owner edits their own Application. Role: Contributor (any scope). Ownership: yes. Grant: n/a. Result: direct edit allowed. Ownership is the signal that unlocks direct edit; the Contributor role is sufficient backing for it.

4. A Contributor with an entity-level grant on one Integration. Role: Contributor (scope does not include Integrations). Ownership: no. Grant: on this one Integration. Result: propose-change on this Integration allowed. Comment on this Integration allowed. Direct edit denied. Delete denied. The grant is a pass for this one Integration only, and it only widens the proposal and comment surfaces, not the direct-edit surface.

5. A Viewer looks at a Business Capability. Role: Viewer. Ownership: n/a. Grant: n/a. Result: read allowed everywhere. Propose, comment, edit, delete all denied. Viewers do not write to the workspace.

6. An Admin deletes an IT Component referenced by three Applications. Role: Admin. Ownership: not relevant. Grant: not relevant. Result: authorization allows delete; the attempt still fails because the IT Component is referenced. The three Applications must drop the reference first. Authorization and referential integrity are independent checks, and both must pass.

7. An owner transfers ownership of an Application to a colleague. Role: Contributor, current owner. Result: the transfer is allowed, and on save, the direct-edit privilege moves with the ownership. The former owner is back on the propose path for that Application unless they also hold a grant or are Admin.

Special cases

Initiatives — restricted UI surface

The Initiative entity is a project-planning artifact, not an architectural entity. To reflect that, the Albumi interface only exposes delete and manage grants actions on Initiatives — editing and proposing changes on an Initiative are not offered in the UI. See Initiatives for why the entity is scoped that way. Automated clients using the API may still reach those operations; the restriction is specifically a UI choice to keep the edit conversation focused on landscape entities.

The root Organization cannot be moved

The workspace’s root Organization is the top of the hierarchy by definition. It is the only Organization allowed to have no parent, and nothing — not even an Admin — can assign a parent to it. This is a property of the data model, not a permission rule: there is no role, grant, or workflow that can nest the root under another node. Rename the root to reflect a rebrand; do not try to reparent it.

Architecture Change Requests — separation of duties

Change Requests (ACRs) are the governance path for proposed changes. Three ACR-specific rules modify the plain role/ownership/grant model:

• Author and reviewer are separate roles on each ACR. The author is the user who created the ACR (its ownerUser in the ACR sense). A reviewer is anyone else who is eligible to approve, reject, or request revision. An author cannot review their own ACR — the same user cannot approve what they wrote.
• Admin may approve their own ACR. The separation-of-duties rule yields to a pragmatic exception for single-Admin workspaces: an Admin who authored an ACR can still approve it, because there would otherwise be no path to move it forward. In larger workspaces this is still a bad habit — pair it with a co-reviewer.
• Entity owners can comment on ACRs that touch their entities. If an ACR proposes changes to an Application you own, you are automatically allowed to comment on that ACR, even if you are not on its review board and did not create it. This is how accountable owners get a voice in reviews of their own entities without requiring a separate grant.

For the full review lifecycle and state machine, see Change Requests and Boards and Sessions.

Multi-workspace membership

A single Albumi account can belong to multiple workspaces. Each membership is independent: its own role, its own ownerships, its own grants. A user switching from workspace A to workspace B is effectively signed in as “the B-role version of themselves” — role and grants are rebound, memberships in A become invisible until the user switches back.

Two consequences worth keeping in mind:

• A user with no workspace context sees nothing. If the application has not established which workspace a request belongs to, the access model has nothing to evaluate against and all queries return empty. This is deliberate: the system fails closed rather than leaking across workspaces.
• Role elevation in one workspace does not affect another. Promoting a user to Admin in workspace A gives them no additional rights in workspace B. If they need equivalent rights there, the B workspace’s Admin has to grant them separately.

Common modeling mistakes

• Using Organizations for access control. The most frequent mistake. Placing all finance applications under the Finance Organization does not restrict editing to finance users. Organization is classification; use ownerUser and per-entity grants for access. See Organizations.
• Assuming a Contributor role equals edit rights. The Contributor role is the workspace-level “can work with landscape entities” footing. It does not give direct-edit rights on entities the user does not own. Without ownership, the Contributor’s path is to propose.
• Expecting an entity-level grant to unlock direct edit. The grant widens propose and comment. It does not turn the grantee into a co-owner, does not allow them to delete or archive the entity, and does not let them transfer ownership. To give someone direct-edit rights, transfer ownership.
• Leaving entities with no owner for a long time. Unowned entities can only be directly edited by Admins, which bottlenecks maintenance. Assign an owner as part of creation, not as a later clean-up.
• Making everyone an Admin to “just get things done”. Admin bypasses the proposal path entirely — the value of the change request workflow disappears if everyone is above it. One or two Admins per workspace is usually enough; give working users the Contributor role and rely on ownership + grants to widen where needed.
• Sharing one account across multiple people. Ownership identifies a single accountable person, the activity log captures who did what, and reviews enforce separation of duties between author and reviewer. Shared accounts break all three. Invite each collaborator as their own user.

Related

• Governance Overview — how the change workflow sits on top of the access model
• Change Requests (ACR) — the proposal, review, and implementation lifecycle
• Boards and Sessions — who reviews and when
• Organizations — why organizational classification is not a permission dimension
• Initiatives — the entity with a restricted edit surface in the UI
• Key Concepts — the short orientation this page expands