Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Stop recommending a replacement ability class

Damian Legawiecfc898029d680
diff --git a/docs/developer/customization/permissions.mdx b/docs/developer/customization/permissions.mdx
index 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 `write
Keys 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 own
A 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