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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Stop recommending a replacement ability class
Damian Legawiecfc898029d680
diff --git a/docs/developer/customization/permissions.mdx b/docs/developer/customization/permissions.mdxindex 229ec7cff0..4f1e327e78 100644--- a/docs/developer/customization/permissions.mdx+++ b/docs/developer/customization/permissions.mdx@@ -11,15 +11,17 @@ Every grantable capability is a flat key of the form `read_<resource>` or `writeKeys are per resource, not per action. The money-adjacent areas (`payments`, `refunds`, `gift_cards`, `store_credits`) are separate resources from `orders`, so "view orders but don't refund" needs no special casing.-Roles as code is plain ActiveRecord:--```ruby-# db/seeds.rb-Spree::Role.find_or_create_by!(name: 'support')- .update!(permissions: %w[read_orders read_customers], description: 'Read-only support')+Roles are data, so create them where you manage the rest of your store's data: **Settings → Staff → Roles** in the dashboard, or the Admin API when you want it scripted.++```bash+spree api post roles --data '{+ "name": "Support",+ "description": "Read-only support",+ "permissions": ["read_orders", "read_customers"]+}'```-A role with `mutable: false` (set from seeds or the console) renders read-only in the dashboard — for roles the application does not want store staff to edit. The `admin` role is always protected.+A role marked immutable renders read-only in the dashboard, for roles the application does not want store staff editing. The `admin` role is always protected.## Registering extension permissions@@ -56,30 +58,13 @@ Naming another audience exposes the scope to a principal outside the store's ownA key never decides *which rows* its holder reaches. That is the controller's job, through scope fetching — a seller holding `write_products` manages their own products because the seller API reads through `current_seller`, not because the key says so.-## Beyond the catalog+## What the catalog does not cover-The catalog is deliberately flat: it answers "may this role touch this kind of record", and that is the whole grant vocabulary. Two rules that do *not* belong in it:+The catalog is deliberately flat: it answers "may this role touch this kind of record", and that is the whole grant vocabulary.-- **Record-state rules** ("a completed order cannot be deleted") live on models and workflows, so they bind every caller — including secret API keys, which never consult CanCanCan.-- **Row-level restrictions** (a support agent limited to one market) are not expressible as keys. Replace the ability class outright:+**Record-state rules** — "a completed order cannot be deleted" — belong on models and workflows, not on roles. Put them there and they bind every caller, including secret API keys, which never consult the role system at all. A rule enforced only in the permission layer is a rule the API can walk straight past.-```ruby-# config/initializers/spree.rb-Spree::Dependencies.ability_class = 'MyApp::Ability'-```--```ruby-# app/models/my_app/ability.rb-class MyApp::Ability < Spree::Ability- def initialize(user, options = {})- super- return unless user.respond_to?(:market_id) && user.market_id-- cannot :manage, Spree::Order- can [:read, :admin], Spree::Order, market_id: user.market_id- end-end-```+**Row-level restrictions**, such as a support agent limited to one market, are not expressible as permission keys. Scope them where the records are read: a controller reaching through `current_store.orders` rather than `Spree::Order` already restricts by tenant, and the same technique narrows by market or seller. See [extending the API](/developer/customization/api).## How enforcement works