From cb43b4705db7e173da606112b37eb35e7c183179 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Fri, 2 Oct 2026 17:53:58 -0500 Subject: [PATCH 1/2] CCSAAS-5490 initiate upload recaptcha GraphQL --- .../schema/uploads/mutations/initiate-upload.md | 14 ++++++++++++++ src/pages/graphql/usage/protected-mutations.md | 1 + 2 files changed, 15 insertions(+) diff --git a/src/pages/graphql/schema/uploads/mutations/initiate-upload.md b/src/pages/graphql/schema/uploads/mutations/initiate-upload.md index 57fc6b7f7..f162729d4 100644 --- a/src/pages/graphql/schema/uploads/mutations/initiate-upload.md +++ b/src/pages/graphql/schema/uploads/mutations/initiate-upload.md @@ -28,6 +28,20 @@ Use the `upload_url` from the response to PUT the file directly to S3. See [Uplo After the file is successfully uploaded, use the [`finishUpload` mutation](finish-upload.md) to complete the upload process. +## reCAPTCHA validation + +Guest shoppers can call the `initiateUpload` mutation without a customer token, for example, to attach an image to a guest return. To limit automated upload requests, merchants can require Google reCAPTCHA validation on this mutation. This setting is disabled by default. To enable it, set [**Enable for Presigned Upload**](https://experienceleague.adobe.com/en/docs/commerce-admin/config/security/google-recaptcha-storefront) in **Stores** > **Configuration** > **Security** > **Google reCAPTCHA Storefront** > **Storefront**. + +When the setting is enabled, each `initiateUpload` request must include a valid reCAPTCHA token in the `X-ReCaptcha` HTTP header: + +```text +X-ReCaptcha: +``` + +If the token is missing or invalid, the request fails and Commerce does not issue a presigned URL. The `finishUpload` mutation does not require a reCAPTCHA token because it can only complete an upload that `initiateUpload` started. + +For more information about reCAPTCHA headers, see [Protected mutations](../../../usage/protected-mutations.md). + ## Syntax ```graphql diff --git a/src/pages/graphql/usage/protected-mutations.md b/src/pages/graphql/usage/protected-mutations.md index 1ba93e7a7..cc33d7997 100644 --- a/src/pages/graphql/usage/protected-mutations.md +++ b/src/pages/graphql/usage/protected-mutations.md @@ -57,6 +57,7 @@ The following table lists the forms and mutations that can be configured to requ | Enable for Checkout/Placing Order | `setPaymentMethodOnCart`, `setPaymentMethodAndPlaceOrder` | | Enable for Coupon Codes | `applyCouponToCart` | | Enable for Resend Confirmation Email | `resendConfirmationEmail` | +| Enable for Presigned Upload | [SaaS only](https://experienceleague.adobe.com/en/docs/commerce/user-guides/product-solutions) `initiateUpload` | ## Related topics From 818e375a43ce878dec2145d4f74ac71dcc697ed9 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Tue, 6 Oct 2026 16:06:50 -0500 Subject: [PATCH 2/2] review --- src/pages/graphql/schema/uploads/mutations/initiate-upload.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/pages/graphql/schema/uploads/mutations/initiate-upload.md b/src/pages/graphql/schema/uploads/mutations/initiate-upload.md index f162729d4..b90fae0c7 100644 --- a/src/pages/graphql/schema/uploads/mutations/initiate-upload.md +++ b/src/pages/graphql/schema/uploads/mutations/initiate-upload.md @@ -30,7 +30,9 @@ After the file is successfully uploaded, use the [`finishUpload` mutation](finis ## reCAPTCHA validation -Guest shoppers can call the `initiateUpload` mutation without a customer token, for example, to attach an image to a guest return. To limit automated upload requests, merchants can require Google reCAPTCHA validation on this mutation. This setting is disabled by default. To enable it, set [**Enable for Presigned Upload**](https://experienceleague.adobe.com/en/docs/commerce-admin/config/security/google-recaptcha-storefront) in **Stores** > **Configuration** > **Security** > **Google reCAPTCHA Storefront** > **Storefront**. +You can call the `initiateUpload` for many reasons, for example to attach an image to a return. To limit automated upload requests, merchants can require Google reCAPTCHA validation on this mutation. This setting is disabled by default. To enable it, set [**Enable for Presigned Upload**](https://experienceleague.adobe.com/en/docs/commerce-admin/config/security/google-recaptcha-storefront) in **Stores** > **Configuration** > **Security** > **Google reCAPTCHA Storefront** > **Storefront**. + +When working with guest shoppers, call the `initiateUpload` mutation without a customer token. When the setting is enabled, each `initiateUpload` request must include a valid reCAPTCHA token in the `X-ReCaptcha` HTTP header: