Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Admin RBAC and Permission Management
Status: Implemented (2026-08-16, PR #14412 and follow-ups) — the permission catalog is the scope vocabulary (Spree::Core::PermissionConfiguration + register_scope), Spree::PermissionSets is deleted with no bridge, roles are pure data on spree_roles (permissions JSON + description + mutable + polymorphic resource), and the surface is live: /admin/roles CRUD, GET /admin/permissions, permission_keys on /admin/me and /seller/me, the dashboard roles page + shared PermissionPicker, locales in all six languages, roles.spec.ts, and a rewritten docs/developer/customization/permissions.mdx. Remaining: the plan's full-page role editor at /settings/roles/$roleId — the dashboard ships a single settings/roles.tsx page instead. 6.1: evaluate removing CanCanCan from the admin path (step 11)
Target: Spree 6.0
Depends on: 5.5-admin-api-key-scopes.md (shipped), 6.0-admin-api.md, 6.0-admin-spa.md, 6.0-platform-auth.md (Customer/Staff split)
Author: Damian (from spree/spree#14164 by @caspianlwoods)
Last updated: 2026-08-27
Summary
Merchants should be able to create staff roles and edit their permissions from the
dashboard, without writing Ruby in an initializer. This plan replaces the
permission-set system with one grant model: a flat catalog of
read_<resource> / write_<resource> keys — the same vocabulary secret API keys
already use (5.5-admin-api-key-scopes.md). Roles
are pure data: keys live on the role row, edited in the dashboard, via the Admin
API, or seeded with plain ActiveRecord — there is no code-managed role concept and
no runtime merge. Code defines the vocabulary (catalog registrations, including
extensions'); data defines the roles. One catalog powers the role editor, the
API-key scope picker, /me, endpoint enforcement, and authorization-failure
diagnostics.
The system is staff-only. The storefront has no roles: customer authorization
is ownership (scope-fetching: current_user.addresses, cart tokens) plus a fixed
internal baseline — not something a merchant edits. B2B company accounts (multiple
users per company, buyer/approver roles, hierarchies, spend limits) are a separate
future Enterprise system with its own vocabulary and are explicitly out of scope
here; sharing a registry with them would poison the meaning of every key
(write_orders means "manage the store's orders" to staff and "place my company's
orders" to a purchaser — those must never be the same token).
Much of what issue #14164 asks for already exists and only needs to be surfaced:
store-scoped role assignments work end to end (Spree::RoleUser + per-store
resolution in Spree::Ability + the staff API), RoleGrantGuard already blocks
privilege-escalating grants, and /me already feeds the dashboard's permission
mirror. What is genuinely new: the catalog registry, a permissions column on
Spree::Role, role CRUD in the Admin API, model-level protection of the admin
role, unified key-based enforcement for both admin principals, and the dashboard
pages.
Key Decisions (do not deviate without discussion)
The grant model
- The permission catalog is the API-key scope vocabulary. Grantable units are
read_<resource>/write_<resource>keys, exactly the tokens inSpree::ApiKey::SCOPES. No parallelorders.readdot-grammar — the scope tokens shipped in 5.5 and are public API. The UI shows translated labels, not raw keys. - Resource granularity, not action granularity — reaffirming the 5.5 scopes
decision. No
cancel_orders/approve_orderskeys. The motivating example ("customer service reads orders but cannot refund") already falls out of resource granularity becausepayments,refunds,gift_cards, andstore_creditsare separate resources fromorders. - Permission sets are deleted at 6.0 — with no compatibility bridge
(2026-08-07). This is a deliberate exception to the "every 6.0 rename keeps
a one-release bridge" convention: it is a system removal, not a rename, and a
behavior-preserving shim would have to carry the runtime-union machinery the
removal exists to kill. Old initializers fail loudly at boot (
NameErroron the deleted set constants;Spree.permissions.assignraises with an upgrade-guide pointer — a tripwire, not a bridge). Migration is genuinely trivial: delete the initializer lines, recreate the role in the editor. Fail-closed is the right failure mode for permissions — nothing boots with staff silently over- or under-privileged. Custom rules that mixed record-level conditions into sets migrate toSpree::Dependencies.ability_class— replacing the ability class outright is the remaining low-level escape hatch (2026-08-08:register_abilitywas dropped too; the catalog plus a full class swap is the whole surface). (Two earlier same-day drafts — sets kept as "bundles" over the catalog, then a one-releaseassignbridge with an import task — were both rejected as complexity serving only back-compat comfort in the breaking window.) - Roles are pure data — there is no code-managed role concept (2026-08-07).
No
Spree.permissions.grant, no runtime merge, no union semantics, no "granted in code" locked rows: the editor is WYSIWYG and the row is the whole truth. "Roles as code" is served by seeds (Spree::Role.find_or_create_by!(name: 'support').update!(permissions: [...])is plain ActiveRecord) or by the Admin API with a secret key. Extensions register catalog resources — never roles. This matches the entire field: Saleor (permission groups via dashboard/GraphQL only), Vendure (roles are DB entities; code defines only the permission catalog and optional initial seeds), Medusa (no OSS RBAC at all), Shopify/commercetools (UI/API only). - Role permissions are a JSON array of concrete keys on
spree_roles, mirroringSpree::ApiKey#scopesstorage exactly (native JSON column,attributedefault[], known-key validation). No join table, no stored aliases (read_all/write_allstay API-key conveniences; the editor offers select-all client-side). - Locked roles use a
mutablecolumn — the NamedType pattern applied to roles (2026-08-07). The admin role seeds withmutable: false(plus a belt-and-braces guard on theadminname); a host that needs a compliance-locked role setsmutable: falsefrom seeds or console and the editor renders it read-only. This covers the one legitimate thing the code path used to provide — roles staff cannot edit — without a second grant source.
Scope of the system
- Staff-only (2026-08-07). The catalog, the editor,
Spree.permissions, and role resolution apply to admin-user principals only.Spree::Abilityresolves roles solely forSpree.admin_user_classprincipals; customer principals get the storefront baseline directly — which also drops a per-requestrole_usersquery for logged-in customers and aligns with the platform-auth Customer/Staff split (a customer holding the admin role stops being a concept at 6.0). - The Store API does not use CanCanCan at all (2026-08-08, superseding the
2026-08-07 "internal baseline" decision).
Spree::Abilityis staff-only; an ability built for a customer principal has no rules. Storefront authorization is ownership, enforced two ways: scope-fetching (every account controller reads throughcurrent_user— addresses, cards, gift cards, store credits, wishlists — and catalog endpoints read the store's public data with no per-record check), andSpree::Storefront::AccessPolicyfor the checks a scope cannot express: cart/order access proven by JWT ownership OR a guest token. The policy is swappable viaSpree::Dependencies.storefront_access_policy_class; denials raiseSpree::Storefront::AccessDenied, rendered as the same 403 payload as CanCan's. The genericauthorize_resource!/authorize_parent!hooks and theaccessible_bycollection filter moved from the shared v3ResourceControllerdown to the Admin branch — the shared base carries no authorization framework. - B2B company accounts extend the storefront through seams, not controller
decoration (2026-08-08). The Enterprise B2B module
(
6.0-channels-catalogs-b2b.md: Company → CompanyLocation → CompanyContact, buyer/approver/viewer contact roles, approvals, spending limits) needs exactly three kinds of authority change, and each has an open-source injection point already in place:- Access widening ("an approver sees every purchase of their company
location") — subclass
Spree::Storefront::AccessPolicy, overridescope/readable?/writable?, register viaSpree::Dependencies.storefront_access_policy_class. Relational scoping is the natural shape here; a rule engine is not — CanCanCan'saccessible_bycannot translate block rules (the token checks) to SQL, which is why the old ability neededauthorize!calls on top of scopes in the first place. - Action vetoes ("orders over the spending limit need approval") —
checkout workflow
validatehooks (carts.complete.validate), shipped with6.0-service-workflows.md. These are order-state policies, not access rules; they never fit an ability cleanly. - Catalog visibility (per-location catalogs/price lists) — data scoping through the products-for-context seam, per the 2026-08-07 decision below. Enterprise implements policy subclasses and hook handlers; open source owns the seams. No CanCanCan and no controller decoration on the storefront — matching Medusa/Saleor/Vendure, none of which ship a storefront rule engine, and Shopify B2B, whose company-contact permissions are fixed roles resolved server-side.
- Access widening ("an approver sees every purchase of their company
location") — subclass
- B2B company roles are out of scope and must stay a separate system
(2026-08-07). Company-account permissions (buyer/approver, location roles,
hierarchies, spend limits, order approvals) are ownership-scoped and
workflow-shaped — what the flat catalog deliberately cannot express — and they
are an Enterprise feature. Industry precedent is unanimous on separation:
commercetools Business Unit associate roles, Shopify B2B company-contact
permissions, and Medusa's B2B employee/spend-limit models are all distinct from
staff RBAC. The polymorphic seams (
RoleUser#user,RoleUser#resource) stay as-is and uncommitted — Enterprise may reuse the storage or ship its own models; this plan promises nothing. - Catalog/product visibility per customer group or company is data scoping,
never a permission key. "Can see catalog B" is a property of what the
storefront query returns (channels/catalogs work,
6.0-channels-catalogs-b2b.md), not of an authorization registry. Non-goal here, recorded so nobody models it as one later.
Enforcement
- The key gate is the primary check for both admin principals (2026-08-07).
ScopedAuthorizationgeneralizes: every admin request resolves a principal key set — a JWT staffer's expanded role keys, a secret key's scopes — and checks<read|write>_<scoped_resource>against it. The per-controllerscoped_resourcedeclaration becomes the enforcement contract for everyone, which is what actually fixes the issue's "menus, API and CanCanCan drift apart" complaint. This supersedes the 5.5 constraint "don't add scope checks to JWT-authenticated paths" (noted there). - CanCanCan is demoted to internal plumbing, not dropped (2026-08-07). Keys
compile to CanCanCan rules behind the gate, because three things still need it:
the storefront baseline's record-level rules, host ability-class swaps,
and sixty-odd admin controllers plus the SPA mirror that speak
authorize!/rules today — rewriting the enforcement layer and the grant model in one release doubles the risk. Nothing public configures CanCanCan anymore. Removing the gem from the admin path becomes a mechanical 6.1+ cleanup option, not a 6.0 goal. - Role protection lives on the model, not in the ability layer. Rename,
permission changes, and destroy are blocked by
Spree::Roleguards keyed offmutable(plus theadmin-name guard), following the 2026-08-05 NamedType decision — ability rules don't fire for secret-key principals, so protection must live where every path hits it. - A role in use cannot be deleted.
can_be_deleted?is false whilerole_usersor pending invitations reference the role. Reassign staff first. - Role CRUD gets the same escalation guard as role assignment. Creating or
updating a role may only grant keys the caller effectively holds (expanded:
write_ximpliesread_xbefore comparison).RoleGrantGuardswitches its comparison from permission-set classes to expanded key sets; secret-key callers are bounded by their own scopes — the anti-amplification rule API keys already have. - 403 diagnostics reuse the scope declaration.
handle_access_deniedaddsdetails: { required_permission: "<read|write>_<scoped_resource>" }— the JWT twin of the shippeddetails.required_scope. Development logs additionally include the caller's roles and effective keys.
Interactively settled 2026-08-07
staffsplits out of thesettingsscope. Newread_staff/write_staffpair covers/admin_users,/invitations,/rolesand the AdminUser/Invitation/Role/RoleUser subjects; those controllers re-scope fromsettingstostaff. Team management is the escalation path and must be grantable separately from store configuration. Accepted trade-off: secret keys minted withsettingsbefore 6.0 lose the staff endpoints — Developer Preview breakage, called out in the release notes.Spree::ApiKey::SCOPESderives from the catalog. Key validation,ScopedAuthorization, and the OpenAPI scope docs read the registry; an extension registering a resource gets the role-editor row and mintableread_x/write_xscopes in one step. Accepted trade-off: the scope list is boot-dynamic — auditing "what can keys do" means consulting the running catalog (/permissions), not a frozen constant.- The role editor is a settings sheet (revised 2026-08-08). The original
call was a full page for the matrix and a members sidebar; in review the
consistency argument won — every other settings resource (tax categories,
payment methods, API keys) edits in a
?edit=<id>/?new=1sheet, and a roles page that navigated away was the odd one out. The members sidebar is dropped with it: the row already shows a member count and Staff owns assignment. One sheet serves create, duplicate and edit. - No seeded roles; the create flow offers client-side templates. "Order
manager" / "Merchandiser" / "Support" presets pre-fill the matrix; nothing
lands in the DB until saved. Accepted trade-off: templates are
dashboard-only — headless/API consumers start from the bare protected
adminrole.
Already true, kept deliberately
- Store-scoped role assignment ships as-is; no new scoping model. Per-store
roles already work (
RoleUser+ ability + staff API). Seller-scoped assignments arrive with6.0-multi-vendor-marketplace.mdthrough the same polymorphicresource. /mekeeps the CanCanCan rules dump and addspermission_keys. The SPA'scan(action, subject)API stays stable — the catalog knows which resource owns each subject, so dashboard-core resolves subject → key internally; the rules dump remains for record-level hints while any remain.
Design Details
Permission catalog
A registry on Spree.permissions (the existing PermissionConfiguration
object), populated by core at boot and open to extensions:
# core registration (engine initializer)
Spree.permissions.register_scope(:orders, group: :orders, resources: -> {
[Spree::Order, Spree::LineItem, Spree::TaxLine, Spree::Discount, Spree::Fee,
Spree::Return, Spree::Exchange, Spree::Claim]
})
# an extension — one call yields the role-editor row AND mintable key scopes
Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> {
[SpreeReviews::Review]
})
Each registration yields two catalog entries — read_<resource> (compiles to
can [:read, :admin], subject per subject) and write_<resource>
(can :manage, subject) — unless write: false (dashboard). Subjects are
lambdas for load-order safety. Labels and descriptions resolve through Spree.t
(spree.permissions.<key>.{label,description}), so backend extensions localize
without touching the SPA.
Core registers one entry per resource of the current scope vocabulary:
| Resource | Group | Subjects (canonical) |
|---|---|---|
orders |
Orders | Order, LineItem, TaxLine, Discount, Fee, Return, Exchange, Claim |
payments |
Orders | Payment |
fulfillments |
Orders | Fulfillment |
refunds |
Orders | Refund |
gift_cards |
Orders | GiftCard, GiftCardBatch |
store_credits |
Orders | StoreCredit |
products |
Catalog | Product, ProductType, Variant, OptionType, OptionValue, Price, PriceList, PriceRule, Asset, ProductPublication |
categories |
Catalog | Category, Taxonomy, ProductCategory |
collections |
Catalog | Collection, ProductCollection, CollectionRule |
stock |
Catalog | StockLevel, StockLocation, StockMovement, StockTransfer, StockReservation |
promotions |
Marketing | Promotion, PromotionRule, PromotionAction, PromotionCategory, CouponCode |
customers |
Customers | Spree.customer_class, Address, CreditCard, CustomerGroup |
settings |
Settings | Store, PaymentMethod, DeliveryMethod, DeliveryZone, Market, Channel, TaxCategory, TaxRate, reasons, MetafieldDefinition, Policy, AllowedOrigin, OrderRoutingRule, … (today's ConfigurationManagement list minus webhooks) |
webhooks |
Settings | WebhookEndpoint, WebhookDelivery |
api_keys |
Access | ApiKey |
staff (new at 6.0) |
Access | Spree.admin_user_class, Invitation, Role, RoleUser |
dashboard (read-only) |
Analytics | :dashboard |
Notes:
- Today
AdminUserandInvitationsubjects are grantable only through SuperUser'smanage :all. Thestaffentry closes that gap so a "Store manager" custom role can manage the team without full admin. Spree::ApiKey::SCOPESbecomes catalog-derived: known-scope validation,ScopedAuthorization, and OpenAPI docs enumerateSpree.permissions.catalog.keysplus theread_all/write_allaliases. Keys minted under a vocabulary that later shrinks stay revocable (the existingscopes_enforceable?guard covers this).- Catalog entries are pure Axis A: flat capability grants, no block conditions,
no domain-invariant
cannotrules (seedecisions.md2026-08-05). Theallow_cancel?/can_be_deleted?block rules currently insideOrderManagement/SuperUsermove to model/workflow guards as part of this work (guard + spec first, then drop the ability condition).
Roles are data
# the only "roles as code" story — plain ActiveRecord in db/seeds.rb (or the Admin API):
Spree::Role.find_or_create_by!(name: 'support')
.update!(permissions: %w[read_orders read_customers], description: 'Read-only support')
Spree::Role gains:
add_column :spree_roles, :description, :string
add_column :spree_roles, :permissions, <jsonb|json>, default: [], null: false
add_column :spree_roles, :mutable, :boolean, default: true, null: false
attribute :permissions, default: []+ normalizing setter — the exactApiKey#scopespattern.- Validation: every key must be a concrete catalog key (no aliases).
- Guards keyed off
mutable(NamedType pattern): name, permissions, and destroy are blocked whilemutableis false. Theadminrole seeds withmutable: falseand additionally can never be renamed or deleted by name guard.can_be_deleted?also requires norole_usersand no pending invitations. - The
adminrole reports the full catalog as its permissions (display); other roles report exactly their stored keys — there is no computed merge.
Spree.permissions ends up doing exactly one thing: catalog registration.
assign raises with an upgrade-guide pointer (tripwire for 5.x initializers);
there is no grant, no bridge, no union.
The storefront leaves CanCanCan entirely: customer/guest requests are
authorized by ownership-scoped queries plus Spree::Storefront::AccessPolicy
(cart/order token checks, order-listing scope), swappable through
Spree::Dependencies.storefront_access_policy_class. Role resolution
(determine_role_names + key activation from the role rows) runs only for
admin-user principals. The admin role activates the full catalog; its former
safety rules are model guards by then.
Spree::Dependencies.ability_class — swapping the whole ability class — is the
remaining low-level escape hatch for host rules that don't fit keys ("support
sees only their region's orders") and the migration target for custom
permission sets that mixed record-level conditions into grants.
Admin API
GET /api/v3/admin/permissions # catalog discovery
GET /api/v3/admin/roles # existing
GET /api/v3/admin/roles/:id # existing
POST /api/v3/admin/roles # new
PATCH /api/v3/admin/roles/:id # new
DELETE /api/v3/admin/roles/:id # new
/permissionsreturns the catalog:[{ key, resource, kind, group, label, description }]. Authenticated,skip_scope_check!(vocabulary, not data — same class as/tags), localized, HTTP-cacheable per boot. Replaces the dashboard's hardcodedSCOPE_GROUPSarray and its "keep in sync with the server" comment.- Roles CRUD on the existing controller (re-scoped to
staff):permitted_paramsarename,description,permissions: [](read/write symmetry with the serializer). Create/update run the key-set escalation check; destroy surfaces the model-guard errors as 422. - Serializer grows
description,permissions,mutable(boolean — false renders read-only in the editor),users_count(assignments on the current store). /meaddspermission_keys(expanded effective keys for the current store) alongside the existing rules dump.- Enforcement: the generalized key gate checks every admin request's
principal key set against
<read|write>_<scoped_resource>; CanCanCan runs behind it (compiled from the same keys), soauthorize!/accessible_byin controllers keep working unchanged during 6.0. - 403 diagnostics:
details.required_permissionfrom thescoped_resourcedeclaration; development logs include roles + effective keys.
Dashboard
- Subject constants: add
Role: 'Spree::Role'todashboard-core'slib/permissions.ts.can(action, subject)keeps its signature; dashboard-core resolves subject → owning resource key via the catalog. - Navigation:
settings.rolesin theteamgroup (position 150, between Staff and API keys), gated bysubject: Subject.Role. - Roles list (
/settings/roles): name, description, permission summary (theScopeListbadge treatment: "Full access" for admin, first N keys + overflow), members count, lock icon on immutable roles. Row actions: edit, duplicate (opens the new-role page pre-filled), delete (confirm; disabled with tooltip whilecan_be_deleted?is false). - Role editor (a sheet on the same page, driven by
?edit=<id>/?new=1, with?from=<id>for duplicate): name, description, then the permission matrix grouped by catalog group — read/write checkboxes per resource (read-only resources render read alone). "Read only" / "Full access" / "Clear" presets. Immutable roles (mutable: false) and callers without update authority get a read-only sheet with no Save. Keys outside the caller's own grant render disabled (the API would reject them — don't offer them). Creating opens with template buttons — Order manager / Merchandiser / Support — pre-filling the matrix client-side; templates are dashboard constants, never DB rows. - Shared picker: the matrix extracts as
components/spree/permission-picker.tsx, driven byusePermissionCatalog()(GET/permissions, store-keyed query). The API-keys page'sScopePickerbecomes a consumer and drops its hardcoded list. - PermissionProvider: refetch
/mewhen the active store changes — rules and keys are store-scoped. ExposepermissionKeys. - Staff page polish: role badges get a permission-summary tooltip; the edit sheet links to the roles page ("Manage roles").
- i18n: all new keys in all six locales (en, de, fr, pl, ar, zh-CN) in both
dashboardanddashboard-coreas appropriate. Core key labels translate client-side; unknown (extension) keys fall back to the server-provided localized label. - E2E:
e2e/roles.spec.ts— create a role with a permission subset, assign it, verify the editor round-trip and the guard (non-admin cannot grant beyond own keys).
SDK and type generation
admin-sdk gains roles.create/update/delete and permissions.list; the Role
type grows the new attributes. Standard pipeline (typelizer → zod → rswag →
OpenAPI regen); rswag integration specs follow the settings resources' pattern.
Migration Path
Phase 1 — backend (core + api):
- Catalog registry + core resource registrations (including
staff);PermissionSets::*deleted outright;assignraises with the upgrade-guide pointer; the install generator's initializer template drops its permission lines in the same change (the template references the deleted constants). - Storefront baseline internalized in
Spree::Ability; role resolution gated to admin-user principals; DB-key activation; Axis A/B extraction (Order#cancel/destroyguards,Spree::Roleprotection guards) — guard + spec first, ability rule removal after. spree_rolesmigration (description,permissions,mutable) + model guards + known-key validation; admin role seededmutable: false.Spree::ApiKey::SCOPESre-pointed at the catalog;admin_users/invitations/rolescontrollers re-scopedsettings→staff;ScopedAuthorizationgeneralized to JWT principals (release-note both Developer Preview breakages).- Roles CRUD +
/permissionsendpoint +/me.permission_keys;RoleGrantGuardkey-set comparison; 403required_permissionenrichment. - Typegen + admin-sdk resources + rswag/OpenAPI.
Phase 2 — dashboard:
usePermissionCatalog+ sharedPermissionPicker; migrate the API-keys scope picker onto it.- Roles list + editor pages (with the template picker), nav entry,
Subject.Role; PermissionProvider store-change refetch; staff page polish. - Locales ×6;
roles.spec.tse2e.
Phase 3 — docs + cleanup:
- Rewrite
docs/developer/customization/permissions.mdxaround the editor, the Admin API, and seeds (with an ability-class swap as the advanced escape hatch); write the 6.0 upgrade-guide entry (below). - 6.1: evaluate removing CanCanCan from the admin path (the storefront keeps it).
No data migration and no bridge. The upgrade-guide entry for hosts coming from
5.x: delete the permission lines from config/initializers/spree.rb (they
raise/NameError at boot otherwise) and recreate any custom roles in
Settings → Roles — or in seeds — before deploying: pre-existing custom role
rows come up with empty permissions, so their staff are locked out (fail
closed) until the matrix is filled in.
Constraints on Current Work
- No new permission sets, anywhere — and no compatibility shims for them.
New capabilities are catalog resource registrations; roles in examples/docs
are data (editor, Admin API, or seeds). Reviewers should reject PRs adding
PermissionSets::classes,assign/grant-style role config, or a bridge resurrecting any of it — the no-bridge removal is a recorded decision, not an oversight. - Every new admin-visible model must appear in a catalog entry. Declaring
scoped_resource(existing rule) is not enough — the models the controller authorizes must be in that resource's subject list, or custom roles cannot reach the endpoint. Reviewers should reject admin PRs that add subjects no entry covers. - Grants stay flat. Record-level conditions belong on models/workflows (Axis B) or in a host ability-class swap — never in the catalog.
- Don't remove the
cannot …, Spree::Role, name: ['admin']ability rules until the model guards land with specs (extraction order: guard first). - New sensitive resources get their own catalog resource rather than riding
settings— splitting later is a breaking vocabulary change. - Storefront authorization must not grow role dependence. Scope-fetching
stays the primary enforcement; nothing storefront-side may consult
Spree::Roleor the catalog.
Open Questions
The design questions raised while drafting (staff scope split, editor container, SCOPES derivation, starter roles, replace-vs-wrap, storefront/B2B boundary, code-managed roles and the migration bridge — the last two dropped entirely) were all resolved 2026-08-07 and live in Key Decisions. Genuinely deferred:
Per-action keys (
approve_orders-style) stay out, reaffirming the 5.5 scopes decision. Unblocked by: a concrete merchant/partner case resource granularity cannot express — revisit both plans together, since the vocabulary is shared.Store-scoped role definitions (a role visible in only one store) — roles stay global reference data; only assignments are store-scoped. Unblocked by: SaaS multi-tenant demand where tenant A's custom roles must be invisible to tenant B.
Seller-scoped assignments — the schema already carries them: a seller staffer is a
RoleUserwithresource: seller(whose store binding derives from the seller's store), invitations accept the same polymorphic resource, and the catalog keys are the same vocabulary (a seller "Catalog manager" holdswrite_products). Direction settled 2026-08-08 for the marketplace plan to inherit:- Same machinery, separate pools. Roles gain an audience (staff |
seller). The operator defines seller capability tiers in the same editor;
sellers assign their people to those tiers but do not define roles.
Shipped 2026-08-16: roles are store-owned (
spree_roles.store_id, required) and unique per(store, name, audience), so each store defines its own tiers and holds its own immutableadmin. Per-seller-owned pools remain a later need — two sellers on one store still cannot each define a "Packer", which is why the operator defines seller tiers. - A per-audience catalog subset. Seller roles draw only from
seller-safe resources (products, orders, fulfillments, stock, analytics —
never
settings,staff,api_keys); the editor filters the grid by audience, and assignment / invitation guards pair audience with resource type. Shipped 2026-08-16 asregister_scope(audiences: %i[store seller])— a list of the audiences beyond staff a resource opens up, rather than a seller-specific boolean, so a third panel adds a value instead of a column (decisions.md 2026-08-16).Spree.permissions.grantable_keys(audience)reads it; a non-staff role validates that it holds only granted keys. - The seller boundary is tenancy, not new keys (Axis A/B): seller-panel
endpoints scope-fetch through
current_sellerexactly as admin endpoints scope throughcurrent_store. The store-admin half of that boundary is enforced in the ability —Spree::Ability#staff_rolesandRoleGrantGuard#caller_rolesmatch onresource_type: 'Spree::Store', notstore_idalone, so a seller-resourced assignment (which binds to the seller's store) confers nothing in the store admin. Regression specs cover it, including anadmin-named seller role.AdminAuthentication's membership check was the hole in that story — it matchedstore_idalone, so a seller-resourced holder authenticated into the admin API with an empty ability and reached the scope-exempt endpoints; tightened 2026-08-16 with a regression spec (marketplace plan Phase 0). The marketplace plan adds the seller-side ability, whichSpree::Abilitynow supports through aresource:option that also confines theadminsuper-role to store resources.
Surface and enforcement ship with
6.0-multi-vendor-marketplace.md, not here. Settled there 2026-08-15 (Decision 10): seller staff areSpree.admin_user_class(noSellerUser), the surface is a dedicated/api/v3/sellerbranch with its ownseller_apiJWT audience, its own strategy registry and audience-stamped refresh tokens, and the seller-side ability isSpree::Abilitywith aresource:option readingresource: sellerassignments. One follow-up lands on this plan's code:AdminAuthentication#current_user_member_of_store?must matchresource_type: 'Spree::Store'likestaff_rolesandRoleGrantGuarddo.- Same machinery, separate pools. Roles gain an audience (staff |
seller). The operator defines seller capability tiers in the same editor;
sellers assign their people to those tiers but do not define roles.
Shipped 2026-08-16: roles are store-owned (
Audit trail for role/permission changes — rides a future admin audit-log feature; not blocking the editor.
CanCanCan-free admin path — becomes possible once nothing public speaks it; evaluate in 6.1.
References
- spree/spree#14164 — the RFC this plan answers
5.5-admin-api-key-scopes.md— scope vocabulary,scoped_resource, guard precedent (partially superseded: catalog-derived SCOPES,staffsplit, JWT key gate)6.0-admin-api.md—/meshape, endpoint inventory (roles block)6.0-admin-spa.md— PermissionProvider, nav registries,<Can>6.0-platform-auth.md— Customer/Staff split (role resolution gated to staff)6.0-channels-catalogs-b2b.md— catalog visibility as data scoping; Company models (B2B roles are a separate future Enterprise system)6.0-multi-vendor-marketplace.md— future seller-scoped role assignmentsdocs/plans/decisions.md2026-08-05 — model-level immutability guards (NamedType precedent) · 2026-08-07 — this plan's catalog/replacement decision- Prior art: Saleor permission groups, Vendure roles, Shopify staff permissions; commercetools Business Unit associate roles / Shopify B2B contact permissions / Medusa B2B module (all keep account roles separate from staff RBAC)