spree_api 5.6.1 → 6.0.0.beta1

data/app/controllers/concerns/spree/api/v3/admin/subclassed_resource.rb

@@ -76,16 +76,16 @@ module Spree
 
           private
 
-          # Per-subclass permitted params. Calls `permitted_params` (the base
-          # allowlist with `type` + `preferences`) and merges in extras the
-          # subclass has declared via `additional_permitted_attributes`.
-          # Controllers can override this hook directly if their subclasses
-          # expose extras through a different mechanism.
+          # Per-subclass permitted params: the controller's own allowlist plus
+          # whatever the concrete subclass declares through
+          # `additional_permitted_attributes`. Controllers can override this
+          # hook directly if their subclasses expose extras through a different
+          # mechanism.
           def permitted_params_for(klass)
             extras = klass.respond_to?(:additional_permitted_attributes) ? klass.additional_permitted_attributes : []
             return permitted_params if extras.blank?
 
-            params.permit(:type, { preferences: {} }, *extras)
+            permitted_params.merge(params.permit(:type, *extras, preferences: {}))
           end
 
           # Default build: top-level resource. Nested controllers (actions,
@@ -115,6 +115,12 @@ module Spree
             preferences.each do |key, value|
               pref_name = key.to_sym
               next unless resource.has_preference?(pref_name)
+              # Internal preferences are Spree's to write — a secret a
+              # provider issued, an id it gave back. They are absent from the
+              # schema, so no form offers them; ignoring them here is what
+              # stops a client writing one anyway and breaking the signature
+              # check that depends on it.
+              next if resource.preference_internal(pref_name)
               # Round-trip guard: clients fetching a record see masked
               # `:password` values. Submitting the mask back unchanged
               # must NOT overwrite the real secret with `••••cret`.

data/app/controllers/concerns/spree/api/v3/admin/validation_details.rb

@@ -0,0 +1,91 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        # Richer validation details for the Admin API.
+        #
+        # The dashboard renders its own copy from its own locale files, so an
+        # admin working in one language never reads a message resolved in the
+        # store's. To let it do that, every entry carries the Rails error
+        # `code` and the interpolation values that go with it; `message` stays
+        # beside it as the fallback for clients without their own translation
+        # (integrations, scripts, and the dashboard's own last resort).
+        #
+        # Store API responses keep the flat `{ attribute => [message] }` shape
+        # — this override is deliberately not in the shared error handler.
+        module ValidationDetails
+          private
+
+          # @param errors [ActiveModel::Errors]
+          # @return [Hash{Symbol => Array<Hash>}] per-attribute error entries
+          def format_validation_details(errors)
+            errors.messages.each_with_object({}) do |(attribute, messages), result|
+              # `details` and `messages` are populated in lockstep by
+              # ActiveModel, so the nth message describes the nth detail. A
+              # message added as a bare string has no symbol and reports a
+              # nil code, which the dashboard reads as "render the message".
+              details = errors.details[attribute] || []
+
+              result[attribute] = messages.each_with_index.map do |message, index|
+                detail = details[index] || {}
+                code = detail[:error].is_a?(Symbol) ? detail[:error] : nil
+
+                # Interpolation values first, so the keys below are the ones
+                # this formatter computed: a validation may itself carry a
+                # `code:` option, and it must not displace the Rails error.
+                detail.except(:error).merge(
+                  code: code,
+                  message: message,
+                  specific: code.present? &&
+                            specific_message?(errors, attribute, code, message, detail.except(:error))
+                )
+              end
+            end
+          end
+
+          # Whether `message` says more than its `code` alone would.
+          #
+          # A code like `:invalid` is generic, and a client holding its own
+          # translation of that code should prefer it. But a model may override
+          # the message for the same code with something far more useful — the
+          # webhook URL validation reports `:invalid` and answers "must be a
+          # valid http or https URL". Replacing that with a translated "is
+          # invalid" loses what the merchant needs.
+          #
+          # Only the server can tell the two apart: the comparison is against
+          # the code's default *in the request's locale*, so it holds for a
+          # store trading in any language. A client cannot do it — it would
+          # have to recognise the default wording in every locale it supports.
+          #
+          # `raise: true` matters. Without it a code Rails has no default for
+          # — every Spree code, whose copy lives under `spree.errors.messages`
+          # — comes back as a "Translation missing" string, which differs from
+          # the message and would mark every one of them as an override.
+          #
+          # The validation's own options come along: rebuilding the default for
+          # `greater_than` without its `count` raises on the missing value.
+          #
+          # @return [Boolean] true when the model supplied its own wording
+          def specific_message?(errors, attribute, code, message, options = {})
+            message != errors.generate_message(attribute, code, **options.symbolize_keys, raise: true)
+          rescue StandardError
+            # Rebuilding the default can fail in several ordinary ways, and none
+            # of them should turn a 422 into a 500:
+            #
+            # - `I18n::MissingTranslationData` — no Rails default at all, which
+            #   is every Spree code.
+            # - `I18n::MissingInterpolationArgument` — the default interpolates
+            #   (`greater_than` wants `count`) but the call site passed only a
+            #   `message:`, so the value was never recorded.
+            # - `NoMethodError` — a nested attribute (`option_values.name`)
+            #   names no method to read.
+            #
+            # In each case there is no default to compare against, so report no
+            # override and let the client translate the code.
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/admin_authentication.rb

@@ -30,9 +30,9 @@ module Spree
         # Secret keys are checked first (server-to-server integrations),
         # then JWT tokens (admin SPA sessions).
         def authenticate_admin!
-          # Try secret API key first
-          @current_api_key = Spree::ApiKey.find_by_secret_token(extract_api_key)
-          @current_api_key = nil if @current_api_key && @current_api_key.store_id != current_store.id
+          # Try secret API key first — the key selects the request's store
+          # (Admin::StoreContext), so there is no store check to make here.
+          @current_api_key = secret_api_key
 
           if @current_api_key
             touch_api_key_if_needed(@current_api_key)
@@ -61,10 +61,14 @@ module Spree
           false
         end
 
+        # Membership is holding a role the store itself owns, mirroring
+        # Spree::Ability#staff_roles. A role belonging to another resource — a
+        # marketplace seller, say — is that panel's business and never admits
+        # its holder here.
         def current_user_member_of_store?
-          return false unless current_user.respond_to?(:role_users)
+          return false unless current_user.respond_to?(:spree_roles)
 
-          current_user.role_users.exists?(store: current_store)
+          current_user.spree_roles.for_resource(current_store).exists?
         end
 
         def set_no_store_cache

data/app/controllers/concerns/spree/api/v3/api_key_authentication.rb

@@ -12,11 +12,13 @@ module Spree
         end
 
         # Authenticates a publishable API key (pk_*) for Store API requests.
-        # Looks up the key by plaintext token scoped to the current store.
+        # The key SELECTS the store — lookup is global by token and
+        # +current_store+ derives from the key (see KeyStoreContext); the key
+        # is never validated against a host-resolved store.
         #
         # @return [Boolean] true if authentication succeeded, false otherwise
         def authenticate_api_key!
-          @current_api_key = current_store.api_keys.active.publishable.find_by(token: extract_api_key)
+          @current_api_key = publishable_api_key
 
           unless @current_api_key
             render_error(
@@ -33,12 +35,12 @@ module Spree
 
         # Authenticates a secret API key (sk_*) for Admin API requests.
         # Computes the HMAC-SHA256 digest of the provided token and looks up
-        # by +token_digest+, then verifies it belongs to the current store.
+        # by +token_digest+. The key is store-bound and selects the request's
+        # store (see Admin::StoreContext).
         #
         # @return [Boolean] true if authentication succeeded, false otherwise
         def authenticate_secret_key!
-          @current_api_key = Spree::ApiKey.find_by_secret_token(extract_api_key)
-          @current_api_key = nil if @current_api_key && @current_api_key.store_id != current_store.id
+          @current_api_key = secret_api_key
 
           unless @current_api_key
             render_error(
@@ -55,6 +57,31 @@ module Spree
 
         private
 
+        # Memoized global publishable-key lookup. Deliberately NOT scoped to
+        # +current_store+ — the store derives from the key, not the other way
+        # around. Memoizes misses too, so pre-authentication callers (store
+        # resolution) don't re-query.
+        #
+        # @return [Spree::ApiKey, nil]
+        def publishable_api_key
+          return @publishable_api_key if defined?(@publishable_api_key)
+
+          @publishable_api_key = Spree::StoreScopeGuard.skip do
+            extract_api_key ? Spree::ApiKey.active.publishable.find_by(token: extract_api_key) : nil
+          end
+        end
+
+        # Memoized global secret-key lookup (digest-based, active keys only).
+        #
+        # @return [Spree::ApiKey, nil]
+        def secret_api_key
+          return @secret_api_key if defined?(@secret_api_key)
+
+          @secret_api_key = Spree::StoreScopeGuard.skip do
+            Spree::ApiKey.find_by_secret_token(extract_api_key)
+          end
+        end
+
         # Marks the API key as used at most once per hour
         # to avoid unnecessary DB writes and job queue pressure on every request.
         # This follows the same approach as GitHub's personal access tokens.
@@ -70,6 +97,15 @@ module Spree
         def extract_api_key
           request.headers['X-Spree-Api-Key'].presence
         end
+
+        # True when the request presents a secret API key token (`sk_` prefix),
+        # regardless of whether authentication has resolved it into
+        # `current_api_key` yet. The token is unverified until
+        # `authenticate_secret_key!` resolves it, so consumers (the scope
+        # guard, rate limiting) must stay fail-closed on this signal alone.
+        def secret_key_request?
+          extract_api_key.to_s.start_with?(Spree::ApiKey::PREFIXES['secret'])
+        end
       end
     end
   end

data/app/controllers/concerns/spree/api/v3/authentication_strategies.rb

@@ -0,0 +1,48 @@
+module Spree
+  module Api
+    module V3
+      # Resolves the authentication strategy a login request asked for, shared by
+      # the Store and Admin auth controllers so the unsupported-provider contract
+      # (error code, status, message) has exactly one definition.
+      #
+      # Including controllers supply the registry and user class.
+      module AuthenticationStrategies
+        extend ActiveSupport::Concern
+
+        private
+
+        # @param provider [String, nil] defaults to the +provider+ param, then :email
+        # @return [Object, nil] a strategy instance, or nil after rendering an error
+        def authentication_strategy(provider = nil)
+          provider ||= params[:provider].presence || 'email'
+
+          strategy = authentication_strategies.build(
+            provider,
+            params: params,
+            request_env: request.headers.env,
+            user_class: authentication_user_class
+          )
+
+          return strategy if strategy
+
+          render_error(
+            code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:invalid_provider],
+            message: "Unsupported authentication provider: #{provider}",
+            status: :bad_request
+          )
+          nil
+        end
+
+        # @return [Spree::Authentication::StrategyRegistry]
+        def authentication_strategies
+          raise NotImplementedError, "#{self.class} must implement #authentication_strategies"
+        end
+
+        # @return [Class]
+        def authentication_user_class
+          raise NotImplementedError, "#{self.class} must implement #authentication_user_class"
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/bulk_operations.rb

@@ -1,11 +1,9 @@
 module Spree
   module Api
     module V3
-      # API-side counterpart to `Spree::Admin::BulkOperationsConcern`. Provides
-      # the shared tag bulk actions, the `bulk_collection` relation, and the
-      # `after_bulk_tags_change` hook controllers override (e.g. to reindex
-      # search + match automatic taxons). Shape mirrors the legacy concern so
-      # the two stay easy to keep in sync.
+      # Provides the shared tag bulk actions, the `bulk_collection` relation,
+      # and the `after_bulk_tags_change` hook controllers override (e.g. to
+      # reindex search + match automatic taxons).
       module BulkOperations
         extend ActiveSupport::Concern
 
@@ -56,7 +54,7 @@ module Spree
 
         # Hook for controllers to perform additional work after bulk tag
         # mutations — e.g. enqueueing search reindex jobs, re-matching
-        # automatic taxons. Mirrors `Spree::Admin::BulkOperationsConcern`.
+        # automatic taxons.
         def after_bulk_tags_change
         end
 

data/app/controllers/concerns/spree/api/v3/cart_resolvable.rb

@@ -6,33 +6,69 @@ module Spree
 
         protected
 
-        # Find cart by prefixed ID and authorize access via CanCanCan.
-        # @return [Spree::Order]
-        def find_cart
-          cart_id = params[:cart_id] || params[:id]
-          @cart = current_store.carts.find_by_prefix_id!(cart_id)
-          authorize!(:show, @cart, cart_token)
+        # Find cart by prefixed ID and authorize read access (owner or guest
+        # token). Completed carts are not carts anymore — they 404 unless the
+        # caller opts in (idempotent completion, payment-session confirm races).
+        # @return [Spree::Cart]
+        def find_cart(include_completed: false)
+          @cart = resolve_cart(include_completed: include_completed)
+          authorize_storefront_read!(@cart, token: cart_token)
           @cart
         end
 
-        # Find the cart and authorize it for update.
-        # @return [Spree::Order]
-        def find_cart!
-          cart_id = params[:cart_id] || params[:id]
-          @cart = current_store.carts.find_by_prefix_id!(cart_id)
-          authorize!(:update, @cart, cart_token)
+        # Find the cart and authorize it for mutation. A completed cart
+        # resolves only for opted-in flows, where mutation is impossible — a
+        # read check is the right bar there.
+        # @return [Spree::Cart]
+        def find_cart!(include_completed: false)
+          @cart = resolve_cart(include_completed: include_completed)
+
+          if @cart.completed?
+            authorize_storefront_read!(@cart, token: cart_token)
+          else
+            authorize_storefront_write!(@cart, token: cart_token)
+          end
+
           @cart
         end
 
-        # Render the cart as JSON using the cart serializer.
+        def resolve_cart(include_completed:)
+          cart_id = params[:cart_id] || params[:id]
+          scope = current_store.carts
+          scope = scope.incomplete unless include_completed
+          scope.find_by_prefix_id!(cart_id)
+        end
+
+        # Render the cart as JSON using the cart serializer. Rendering never
+        # mutates: an action that wants unbuyable lines swept calls
+        # +sweep_unbuyable_lines!+ itself first.
         def render_cart(status: :ok)
-          @cart = @cart.remove_out_of_stock_items!
           render json: Spree.api.cart_serializer.new(@cart, params: serializer_params).to_h, status: status
         end
 
-        # Render the order as JSON using the order serializer (for complete action).
+        # Drops lines the customer can no longer buy — a discontinued product,
+        # or stock that ran out while the cart sat idle. For reads of a cart
+        # the customer is returning to, never for the write that just
+        # happened: an add a stock check already approved must not be
+        # second-guessed in the same request, and an external inventory
+        # provider makes that contradiction routine, since the provider
+        # answers the write while the sweep reads Spree's own rows.
+        def sweep_unbuyable_lines!
+          @cart = @cart.remove_out_of_stock_items!
+        end
+
+        # Render what the checkout produced (for the complete action).
+        #
+        # A checkout spanning several sellers produced a group of orders rather
+        # than one order, and the group is what the customer bought — so it is
+        # what comes back, with the per-seller orders nested inside it. A
+        # storefront that knows nothing about groups still finds every order it
+        # needs there.
         def render_order(status: :ok)
-          render json: Spree.api.order_serializer.new(@cart.reload, params: serializer_params).to_h, status: status
+          record = @cart.reload
+          serializer = record.is_a?(Spree::OrderGroup) ? Spree.api.order_group_serializer : Spree.api.order_serializer
+
+          render json: serializer.new(record, params: serializer_params).to_h, status: status
         end
 
         # Return the cart token from the request headers.

data/app/controllers/concerns/spree/api/v3/company_address_writes.rb

@@ -0,0 +1,37 @@
+module Spree
+  module Api
+    module V3
+      # Writing an entry in a company node's address book, on either API.
+      #
+      # An entry is an ordinary address the node owns, so the payload is
+      # address attributes plus the label it is filed under. The two defaults
+      # are not columns on the row — they are pointers on the node — so they
+      # travel to the address services as flags, which apply them once the
+      # address itself is written.
+      module CompanyAddressWrites
+        extend ActiveSupport::Concern
+
+        protected
+
+        def permitted_params
+          params.permit(:label, *Spree::Api::V3::AddressParams::ADDRESS_KEYS)
+        end
+
+        # @return [Hash] default keywords for Spree::Addresses::Create / Update
+        def default_flags
+          { default_billing: flag_param(:default_billing), default_shipping: flag_param(:default_shipping) }
+        end
+
+        # Each flag has three meanings and they are all different: true claims
+        # the slot, false gives it up, and saying nothing leaves it alone.
+        #
+        # @return [Boolean, nil] nil when the client said nothing about it
+        def flag_param(name)
+          return nil unless params.key?(name)
+
+          ActiveModel::Type::Boolean.new.cast(params[name])
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/current_password_confirmation.rb

@@ -0,0 +1,41 @@
+module Spree
+  module Api
+    module V3
+      # Re-asks for the account password before something irreversible.
+      #
+      # Shared because the check must not drift: a customer class may
+      # authenticate through `valid_password?` or `authenticate` depending on
+      # what the host app swapped in, and a second copy of that ladder is a
+      # second thing to remember when it changes. One of the two call sites
+      # gates permanent erasure.
+      module CurrentPasswordConfirmation
+        extend ActiveSupport::Concern
+
+        private
+
+        # @return [Boolean] whether `current_password` matches the signed-in
+        #   account. False when the parameter is missing — an absent password
+        #   is not a correct one.
+        def valid_current_password?
+          return false if params[:current_password].blank?
+
+          if current_user.respond_to?(:valid_password?)
+            current_user.valid_password?(params[:current_password])
+          elsif current_user.respond_to?(:authenticate)
+            current_user.authenticate(params[:current_password]).present?
+          else
+            false
+          end
+        end
+
+        def render_current_password_invalid
+          render_error(
+            code: ErrorHandler::ERROR_CODES[:current_password_invalid],
+            message: Spree.t(:current_password_invalid, scope: :api),
+            status: :unprocessable_content
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/direct_uploads.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module V3
+      # Presigning for direct-to-storage uploads: a caller exchanges blob
+      # metadata for an upload URL and gets back a signed id to reference when
+      # it creates or updates a resource.
+      #
+      # Shared by the admin and seller branches because the exchange itself is
+      # audience-neutral — a blob created here is attached to nothing. What
+      # differs is the gate each branch puts in front of it, which stays on the
+      # including controller as its `scoped_resource`.
+      module DirectUploads
+        extend ActiveSupport::Concern
+
+        def create
+          blob = ActiveStorage::Blob.create_before_direct_upload!(**blob_params)
+
+          render json: {
+            direct_upload: {
+              url: blob.service_url_for_direct_upload,
+              headers: blob.service_headers_for_direct_upload
+            },
+            signed_id: blob.signed_id
+          }, status: :created
+        end
+
+        private
+
+        def blob_params
+          params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/spree/api/v3/error_handler.rb

@@ -13,6 +13,10 @@ module Spree
           invalid_token: 'invalid_token',
           invalid_provider: 'invalid_provider',
           invalid_refresh_token: 'invalid_refresh_token',
+          # Distinct from authentication_failed: the person proved who they are to
+          # the identity provider, but no account here is authorized for them.
+          account_not_provisioned: 'account_not_provisioned',
+          invalid_oauth_state: 'invalid_oauth_state',
           current_password_invalid: 'current_password_invalid',
           password_reset_token_invalid: 'password_reset_token_invalid',
           redirect_url_not_allowed: 'redirect_url_not_allowed',
@@ -36,12 +40,15 @@ module Spree
           # Order errors
           order_not_found: 'order_not_found',
           order_cannot_complete: 'order_cannot_complete',
+          discount_not_editable: 'discount_not_editable',
 
           # Line item errors
           line_item_not_found: 'line_item_not_found',
           variant_not_found: 'variant_not_found',
           insufficient_stock: 'insufficient_stock',
           invalid_quantity: 'invalid_quantity',
+          invalid_price: 'invalid_price',
+          price_override_not_allowed: 'price_override_not_allowed',
 
           # Validation errors
           validation_error: 'validation_error',
@@ -85,12 +92,12 @@ module Spree
           # Override base controller error handlers
           rescue_from ActiveRecord::RecordNotFound, with: :handle_record_not_found
           rescue_from CanCan::AccessDenied, with: :handle_access_denied
+          rescue_from Spree::Storefront::AccessDenied, with: :handle_access_denied
           rescue_from Spree::Core::GatewayError, with: :handle_gateway_error
           rescue_from ActionController::ParameterMissing, with: :handle_parameter_missing
           rescue_from ActiveRecord::RecordInvalid, with: :handle_record_invalid
           rescue_from ArgumentError, with: :handle_argument_error
           rescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_parse_error
-          rescue_from StateMachines::InvalidTransition, with: :handle_invalid_transition
         end
 
         protected
@@ -122,12 +129,33 @@ module Spree
           )
         end
 
+        # Maps symbolic line-item rejections onto the API error-code vocabulary.
+        #
+        # @param errors [ActiveModel::Errors, Object] structured rejection from a workflow
+        # @param default [String] fallback when no recognized symbol is present
+        # @return [String] a value from {ERROR_CODES}
+        def infer_line_item_error_code(errors, default:)
+          return default unless errors.is_a?(ActiveModel::Errors)
+
+          base_symbols = (errors.details[:base] || []).pluck(:error)
+          return ERROR_CODES[:price_override_not_allowed] if base_symbols.include?(:price_override_not_allowed)
+          return ERROR_CODES[:invalid_price] if base_symbols.include?(:invalid_price)
+          return ERROR_CODES[:invalid_quantity] if base_symbols.include?(:quantity_rule_violated)
+
+          default
+        end
+
         # Convenience method for service result errors
         def render_service_error(error, code: ERROR_CODES[:processing_error], status: :unprocessable_content)
           if error.is_a?(ActiveModel::Errors)
             render_validation_error(error, code: code)
           elsif error.is_a?(String)
             render_error(code: code, message: error, status: status)
+          elsif error.is_a?(Symbol)
+            # Workflows reject with a symbol naming the reason. Translate it,
+            # falling back to the symbol so a missing key is visible rather
+            # than silently blank.
+            render_error(code: code, message: Spree.t(error, default: error.to_s.humanize), status: status)
           else
             render_error(code: code, message: error.to_s, status: status)
           end
@@ -161,10 +189,33 @@ module Spree
           render_error(
             code: ERROR_CODES[:access_denied],
             message: exception.message,
-            status: :forbidden
+            status: :forbidden,
+            details: access_denied_details
           )
         end
 
+        # Names the catalog permission the failed request needed, derived from
+        # the controller's `scoped_resource` declaration — the JWT twin of the
+        # scope check's `required_scope` (docs/plans/6.0-admin-rbac.md). Only
+        # reported when the caller genuinely lacks the key: a denial the caller
+        # is capability-authorized for is a record- or store-level condition,
+        # and naming a permission they already hold would mislead.
+        def access_denied_details
+          return unless respond_to?(:scoped_resource_name, true)
+
+          resource = scoped_resource_name
+          return unless resource
+
+          required = "#{action_kind}_#{resource}"
+          return unless Spree.permissions.key?(required)
+
+          ability = current_ability
+          return unless ability.respond_to?(:permission_keys)
+          return if ability.permission_keys.include?(required)
+
+          { required_permission: required }
+        end
+
         def handle_gateway_error(exception)
           Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
           render_error(
@@ -207,15 +258,6 @@ module Spree
           )
         end
 
-        def handle_invalid_transition(exception)
-          Rails.error.report(exception, context: error_context, source: 'spree.api.v3')
-          render_error(
-            code: ERROR_CODES[:cart_cannot_transition],
-            message: exception.message,
-            status: :unprocessable_content
-          )
-        end
-
 
         private
 

data/app/controllers/concerns/spree/api/v3/idempotent.rb

@@ -67,10 +67,16 @@ module Spree
         end
 
         def idempotency_cache_key(key)
-          owner_id = request.headers['X-Spree-Api-Key'].presence ||
-                     spree_current_user&.id ||
-                     request.remote_ip
-          "spree:idempotency:#{Digest::SHA256.hexdigest(owner_id.to_s)}:#{Digest::SHA256.hexdigest(key)}"
+          credential = request.headers['X-Spree-Api-Key'].presence ||
+                       spree_current_user&.id ||
+                       request.remote_ip
+          # The resolved store partitions the namespace: a staff JWT spans
+          # stores, and replaying one store's cached response for a request
+          # aimed at another would cross store boundaries. The resolved
+          # store — not the raw header — so a header naming the default store
+          # and no header at all land in the same partition, as they resolve
+          # to the same store.
+          "spree:idempotency:#{Digest::SHA256.hexdigest("#{credential}\0#{current_store&.id}\0#{key}")}"
         end
 
         def request_fingerprint