The Permission Matrix Is a Product Surface

A permission request usually arrives as something small.

“Can we add a manager role?” “Can finance see billing but not projects?” “Can a store operator invite an agency, but only for one region?” “Can a customer keep advanced reporting after downgrading until the end of the quarter?”

Each request sounds like a setting. Together, they expose the product’s model of the customer organization: who counts as an admin, where authority begins and ends, which features belong to which package, what happens during account changes, and who can explain a decision later.

That is why a permission matrix is not just an admin table. For SaaS and ecommerce platforms, it is a product surface.

Access Is Not One Thing

Product teams often talk about permissions as if access were one question. It is usually at least two.

The first question is: what can this person do inside the account? Stripe’s User roles documentation is a useful concrete example because it frames roles as controlled access with specific permissions. It also warns that when one person has multiple roles, the permissions combine, which can create conflicts or unintended authority.

The second question is: what has this account earned, bought, qualified for, or retained? Stripe’s Entitlements documentation describes mapping internal service features to products, then granting or revoking customer feature access through subscription state and product-feature mappings.

Customers do not experience those as separate architecture concerns. They experience both as access. A user can enter a reporting view, export a data file, invite an agency, activate a premium feature, or they cannot. If roles and entitlements are modeled separately but explained together poorly, the product feels inconsistent even when each system is internally logical.

The Matrix Shows the Customer Organization

A useful permission matrix has more than rows of role names and columns of actions. It makes the product’s assumptions visible:

• Actor: which human, service account, partner, agency, or support user is acting.
• Role: what durable responsibility the actor has.
• Resource: the object being touched, such as a project, workspace, store, catalog, order, billing account, report, or API key.
• Scope: whether the action applies to one object, one team, one store, one region, one brand, or the whole organization.
• Action: view, create, edit, approve, publish, export, invite, configure, delete, impersonate, or override.
• Entitlement: whether the feature belongs to the customer’s current package or subscription state.
• Visibility: whether the user can see unavailable actions and understand why they are unavailable.
• Exception path: who can grant temporary or custom access and how that exception expires.
• Audit trail: who can later answer what happened, when, and under which rule.

If the matrix does not answer these questions, the interface will improvise. Sales will promise a custom role. Support will keep a private checklist. Engineering will add a condition near the feature code. The admin UI will grow another toggle with a name only the team understands.

Complexity Appears Before the UI Breaks

The first visible symptom is usually a confusing settings page. The deeper issue is an unclear model.

Figma’s permissions DSL case study is useful here as a bounded example. Figma described building a custom permissions language after its permissions system could no longer handle the product’s needs cleanly. That does not mean every SaaS product needs a DSL. It does mean collaborative products can outgrow scattered permission checks long before the problem is obvious in a quarterly roadmap review.

Product leaders should catch that earlier. Before adding a role, ask what new customer shape the role represents. Before adding a permission, ask whether it belongs to the actor, the resource, the package, the lifecycle state, or an exception. Before adding an enterprise toggle, ask who will explain it in onboarding, security review, renewal, and support.

Role Names Must Match Customer Mental Models

Permission design is not only policy design. It is language design.

If the customer says “store manager,” “brand admin,” “regional operator,” “finance owner,” or “agency partner,” those labels carry expectations. They imply the work someone owns, the risks they are allowed to take, and the parts of the account they should never touch.

NN/g’s card-sorting guidance describes card sorting as a way to see how users group topics so information architecture can better match expectations. For permissions, the method is most useful around labels, groupings, and delegation concepts: which actions customers think belong together, which roles feel natural, and where the product’s categories feel alien.

It is not a security validator. A card sort will not prove that a permission model is safe, complete, or compliant. But it can show when the product is asking customers to operate inside an internal taxonomy. That matters because admins delegate work using their organization’s language, not the product team’s architecture.

Where Permission Matrices Usually Break

Most permission problems start in one of seven places.

First, the role is a job title, not a responsibility. “Manager” sounds familiar, but it may hide several different jobs: approving spend, inviting users, editing settings, publishing content, or viewing analytics.

Second, the scope is unclear. A user can manage a catalog, but is that catalog global, regional, brand-specific, or store-specific?

Third, entitlements and roles collide. The person may have permission to use advanced reporting, while the account is no longer entitled to that feature after a downgrade. Or the account may have the feature, while the user lacks the right internal role.

Fourth, inherited access is invisible. Users see an action but cannot tell whether it came from a team, parent organization, package, manual override, support action, or migration rule.

Fifth, exceptions never expire. Custom access created to close one deal becomes permanent product behavior.

Sixth, audit events are designed after the incident. If the system cannot explain why access existed at the time of action, support and security teams inherit the ambiguity.

Seventh, support becomes the policy engine. When every edge case requires a ticket, the product has not actually modeled the customer’s operating reality.

A Product-Leader Audit

Before approving another role or toggle, run a permission-matrix audit. Keep it practical. The goal is not to produce a perfect architecture diagram. The goal is to expose where the product has avoided making decisions.

1. List the real actors. Include customer admins, operators, finance users, external agencies, developers, support agents, service accounts, and procurement or compliance reviewers.

2. List the resources they touch. In ecommerce, that may include stores, catalogs, products, prices, promotions, orders, customer records, payments, exports, and analytics. In SaaS, it may include workspaces, projects, seats, integrations, API keys, billing, reports, and audit logs.

3. Separate actions from packages. “Can export data” is an action. “Advanced exports are part of the Enterprise plan” is an entitlement. Both matter, but they should not be blurred.

4. Add lifecycle states. Trial, active, overdue, suspended, downgraded, migrated, invited, pending approval, and offboarded accounts often need different access behavior.

5. Mark visibility rules. Decide when to hide an action, disable it with explanation, show an upgrade path, or route to an admin.

6. Name exception owners. If custom access is allowed, define who can grant it, why, where it is recorded, and when it expires.

7. Define audit events before launch. The matrix should say which permission decisions need a durable record and who can read it.

8. Assign product ownership. Security, engineering, legal, support, and customer success all have a stake. But if no product owner holds the customer model, the matrix will drift toward implementation detail.

Keep the Boundary Clear

This is not an argument for product teams to bypass security or compliance. It is the opposite. A clearer product model gives security, engineering, and legal partners something concrete to review.

It is also not a call for every early product to build enterprise-grade role design. Small products often need fewer roles, not more. The right question is whether the current matrix honestly matches the customer organization the product already serves.

When it does, the admin UI can be simpler. Role descriptions become clearer. Upgrade prompts make more sense. Support can explain decisions without reading code. Customers can delegate work without guessing what a role really means.

A permission matrix is where your product decides what kinds of organizations it can serve. Treat it like a product surface before your customers are forced to do it for you.