@spree/docs 0.1.93 → 0.1.94

package/dist/developer/how-to/custom-api-authentication.md

@@ -1,6 +1,6 @@
 ---
 title: Integrate a Third-Party Identity Provider
-description: Step-by-step guide to plugging a custom identity provider (Auth0, Okta, Firebase, Cognito, or any JWT issuer) into the Spree Store API.
+description: Step-by-step guide to plugging a custom identity provider (Auth0, Okta, Firebase, Cognito, or any JWT issuer) into the Spree Store and Admin APIs.
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -8,19 +8,35 @@ import { Since } from '/snippets/since.mdx';
 
 ## Overview
 
-Spree's Store API ships with a pluggable authentication system. You register a **strategy class** for a named provider, and the existing login endpoints will dispatch to it — no controller patching, no route overrides, no fork.
+Both Spree APIs — the customer-facing **Store API** and the back-office **Admin API** — ship with the same pluggable authentication system. You register a **strategy class** for a named provider, and the existing login endpoints dispatch to it — no controller patching, no route overrides, no fork.
 
 By the end of this guide you'll have:
 
 - A custom strategy that verifies a third-party JWT against a JWKS endpoint
 - A user account auto-provisioned on first login, reused on subsequent logins
 - A standard **Spree-issued JWT + refresh token** returned to the client
-- All Store API endpoints (cart, checkout, account) protected by Spree's own JWT — the third-party token is only used at the exchange step
+- Every API endpoint protected by Spree's own JWT — the third-party token is only used at the login exchange step
 
-> **INFO:** The same pattern works for Admin API integrations via `admin_authentication_strategies`. Examples in this guide target the Store API; substitute `Spree.admin_user_class` and the admin endpoints where noted.
+### Store vs Admin — what changes
+
+The mechanism is identical for both surfaces. A strategy you write works on either side; only the registry you add it to (and a handful of surface-specific details) differ:
+
+| | Store API (customers) | Admin API (staff) |
+|---|---|---|
+| Registry | `Spree.store_authentication_strategies` | `Spree.admin_authentication_strategies` |
+| User class | `Spree.user_class` | `Spree.admin_user_class` |
+| Login endpoint | `POST /api/v3/store/auth/login` | `POST /api/v3/admin/auth/login` |
+| Refresh endpoint | `POST /api/v3/store/auth/refresh` | `POST /api/v3/admin/auth/refresh` |
+| JWT audience | `aud: store_api` | `aud: admin_api` |
+| Refresh token delivery | returned in the response body | set as an `HttpOnly` cookie |
+| Strategy base class | `Spree::Authentication::Strategies::BaseStrategy` | *(same)* |
+
+Everything else — the strategy class you write, the `BaseStrategy` helpers, JWT verification, account provisioning, account linking — is the same. The walkthrough below uses the Store API; each step calls out the one-line Admin swap.
 
 ## Architecture
 
+The flow below uses the Store API; the Admin API is identical with `admin` in the path and `aud: admin_api` on the issued JWT.
+
 ```
 Client → POST /api/v3/store/auth/login
             { provider: "my_idp", token: "<third-party JWT>" }
@@ -127,15 +143,33 @@ end
 
 ## Step 2: Register the Strategy
 
-Add the strategy to `Spree.store_authentication_strategies` in an initializer. The key you choose here is what clients will send as `provider` in the login payload.
+Add the strategy to a registry in an initializer. **This is the only line that decides which API the provider serves** — `store_authentication_strategies` for customer login, `admin_authentication_strategies` for staff login. Register with both to allow the same provider on either surface. The key you choose here is what clients send as `provider` in the login payload.
 
-```ruby config/initializers/spree.rb
+
+```ruby Store API
+# config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.store_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
 end
 ```
 
-`Spree.store_authentication_strategies` is a `Spree::Authentication::StrategyRegistry`. The full API:
+```ruby Admin API
+# config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.admin_authentication_strategies.add(:okta, MyApp::Auth::OktaStrategy)
+end
+```
+
+```ruby Both
+# config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.store_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
+  Spree.admin_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
+end
+```
+
+
+Both registries are a `Spree::Authentication::StrategyRegistry` with the same API:
 
 | Method | Purpose |
 |---|---|
@@ -144,19 +178,18 @@ end
 | `[key]` | Look up a registered class. |
 | `key?(key)`, `keys`, `values`, `each`, `to_h` | Standard introspection. |
 
-> **WARNING:** `Spree::UserIdentity` validates that `provider` is a registered strategy key. Registration must happen during boot — before the first login attempt.
+The strategy is instantiated with the surface's user class automatically — `Spree.user_class` from the store registry, `Spree.admin_user_class` from the admin registry — and your `authenticate` reads it via the `user_class` helper, so the same class provisions customers on one side and staff on the other.
 
-For an admin-side equivalent, register under `Spree.admin_authentication_strategies` instead and instantiate your strategy against `Spree.admin_user_class`:
+> **TIP:** Restrict a surface to SSO by removing the built-in email/password strategy after adding yours: `Spree.admin_authentication_strategies.remove(:email)` locks staff to your provider; the store side stays on email/password.
 
-```ruby
-Spree.admin_authentication_strategies.add(:okta, MyApp::Auth::OktaStrategy)
-```
+> **WARNING:** `Spree::UserIdentity` validates that `provider` is a registered strategy key. Registration must happen during boot — before the first login attempt.
 
 ## Step 3: Call the Exchange Endpoint
 
-`POST /api/v3/store/auth/login` is the single dispatcher. The `provider` field in the body selects the strategy — omit it for built-in email/password, set it to your registered key for everything else. The remaining body fields are whatever your strategy reads from `params`.
+The login endpoint is the single dispatcher — `/api/v3/store/auth/login` for customers, `/api/v3/admin/auth/login` for staff. The `provider` field in the body selects the strategy — omit it for built-in email/password, set it to your registered key for everything else. The remaining body fields are whatever your strategy reads from `params`.
 
-```http
+
+```http Store API
 POST /api/v3/store/auth/login
 X-Spree-API-Key: pk_your_publishable_key
 Content-Type: application/json
@@ -167,21 +200,45 @@ Content-Type: application/json
 }
 ```
 
-The response is the standard Spree auth payload:
+```http Admin API
+POST /api/v3/admin/auth/login
+X-Spree-API-Key: sk_your_secret_key
+Content-Type: application/json
+
+{
+  "provider": "okta",
+  "token":    "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."
+}
+```
+
+
+The response is the standard Spree auth payload. The difference is the refresh token: the **Store API returns it in the body**, while the **Admin API sets it as an `HttpOnly` cookie** scoped to `/api/v3/admin/auth` and omits it from the body.
+
 
-```json
+```json Store API
 {
   "token":         "<Spree HS256 JWT, aud=store_api>",
   "refresh_token": "rt_xxxxxxxxxxxx",
-  "user":          { "id": "user_...", "email": "...", "first_name": "...", "...": "..." }
+  "user":          { "id": "user_...", "email": "...", "...": "..." }
 }
 ```
 
-From here, the client sends `Authorization: Bearer <Spree JWT>` on every subsequent Store API call. When the JWT expires (default: 1 hour), the client hits `POST /api/v3/store/auth/refresh` with the refresh token to rotate both.
+```json Admin API
+{
+  "token": "<Spree HS256 JWT, aud=admin_api>",
+  "user":  { "id": "user_...", "email": "...", "...": "..." }
+}
+```
 
-From `@spree/sdk` the same call looks like:
+The refresh token arrives as a `Set-Cookie: spree_admin_refresh_token=…; HttpOnly; Path=/api/v3/admin/auth` response header rather than in the body.
 
-```ts
+
+From here, the client sends `Authorization: Bearer <Spree JWT>` on every subsequent call. When the JWT expires (default: 1 hour), it rotates via the refresh endpoint — the Store API takes the refresh token in the body of `POST /api/v3/store/auth/refresh`; the Admin API drives `POST /api/v3/admin/auth/refresh` entirely from the cookie (see [Admin Auth & Cookie Refresh](../../api-reference/admin-api/authentication.md)).
+
+The SDKs wrap the same exchange — `@spree/sdk` for the Store API, `@spree/admin-sdk` for the Admin API:
+
+
+```ts Store SDK
 import { createClient } from '@spree/sdk'
 
 const client = createClient({ baseUrl: 'https://your-store.com', publishableKey: '<pk>' })
@@ -192,6 +249,19 @@ const auth = await client.auth.login({
 })
 ```
 
+```ts Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({ baseUrl: 'https://your-store.com' })
+
+// Refresh token lands in the HttpOnly cookie; only the access token comes back here.
+const auth = await client.auth.login({
+  provider: 'okta',
+  token:    thirdPartyJwt,
+})
+```
+
+
 `LoginCredentials` is a discriminated union — pass `{ email, password }` for the built-in strategy, or `{ provider, ...customFields }` for any strategy you registered.
 
 ## Account Linking
@@ -225,20 +295,29 @@ end
 
 ## Logout
 
-```http
+
+```http Store API
 POST /api/v3/store/auth/logout
 Content-Type: application/json
 
 { "refresh_token": "rt_xxxxxxxxxxxx" }
 ```
 
+```http Admin API
+POST /api/v3/admin/auth/logout
+Content-Type: application/json
+
+# No body — the refresh token is read from the HttpOnly cookie and cleared.
+```
+
+
 This revokes the Spree refresh token. The Spree JWT itself remains valid until it expires naturally (short-lived by design — default 1 hour). Spree does **not** call the IdP's revocation endpoint; if you need single sign-out, do that from the client.
 
 ## Security Notes
 
 A few things worth getting right:
 
-- **Don't try to pass the third-party JWT through to protected endpoints.** Spree's `JwtAuthentication` concern verifies `iss: 'spree'` and `aud: 'store_api'` with HS256 against the Spree secret — a foreign RS256 token will never validate, and you don't want it to. The exchange-at-login model is the right one.
+- **Don't try to pass the third-party JWT through to protected endpoints.** Spree's `JwtAuthentication` concern verifies `iss: 'spree'` and the expected audience (`store_api` or `admin_api`) with HS256 against the Spree secret — a foreign RS256 token will never validate, and you don't want it to. The exchange-at-login model is the right one.
 - **JWKS caching and rotation.** Cache the JWKS (the example uses a 1-hour TTL) but make sure your loader honors the `invalidate: true` option so that an unrecognized `kid` triggers a refetch. Otherwise key rotation at the IdP locks users out for up to the TTL.
 - **Validate `iss` and `aud` claims.** Always. The example passes `verify_iss: true, verify_aud: true` to `JWT.decode` — don't drop those.
 - **Algorithm pinning.** Hard-code `algorithms: ['RS256']` (or whatever your IdP uses). Never let the token's own `alg` header decide — the classic `alg: none` and HS-as-RS confusion attacks both exploit lax algorithm selection.
@@ -297,5 +376,6 @@ end
 - `Spree::Authentication::Strategies::BaseStrategy` — `spree/core/app/models/spree/authentication/strategies/base_strategy.rb`
 - `Spree::UserIdentity` — `spree/core/app/models/spree/user_identity.rb`
 - `Spree::Api::V3::Store::AuthController` — `spree/api/app/controllers/spree/api/v3/store/auth_controller.rb`
+- `Spree::Api::V3::Admin::AuthController` — `spree/api/app/controllers/spree/api/v3/admin/auth_controller.rb`
 - `Spree::Api::V3::JwtAuthentication` — `spree/api/app/controllers/concerns/spree/api/v3/jwt_authentication.rb`
-- See also: [Authentication](../customization/authentication.md) for `Spree.user_class` integration.
+- See also: [Staff & Roles](../core-concepts/staff-roles.md) for the admin login flow, [Customers](../core-concepts/customers.md) for storefront auth, and [Authentication](../customization/authentication.md) for `Spree.user_class` integration.

package/dist/developer/multi-store/quickstart.md

@@ -4,7 +4,7 @@ sidebarTitle: Quickstart
 description: Enable multiple storefronts on a single Spree app with the spree_multi_store gem, including per-store products, payment methods, taxonomies, and promotions.
 ---
 
-To enable multiple stores, you will need to add the `spree_multi_store` gem to your project via:
+To enable multiple stores, you will need to add the [spree_multi_store](quickstart.md) gem to your project via:
 
 
 ```bash Spree CLI (Docker)

package/dist/developer/sdk/admin/authentication.md

@@ -78,7 +78,7 @@ try {
 
 ### Identity providers
 
-`auth.login()` also accepts third-party identity-provider payloads when the server has a matching strategy registered in `Spree.store_authentication_strategies`:
+`auth.login()` also accepts third-party identity-provider payloads when the server has a [matching strategy registered](../../how-to/custom-api-authentication.md):
 
 ```typescript
 const { token } = await client.auth.login({ provider: 'auth0', token: idpJwt })

package/dist/developer/sdk/admin/resources.md

@@ -6,6 +6,8 @@ description: "Reference for every @spree/admin-sdk resource — products, orders
 
 Every Admin API resource is exposed as a property on the client (`client.orders`, `client.products`, …). Collection resources follow a consistent CRUD shape — `list`, `get`, `create`, `update`, `delete` — plus resource-specific actions. Nested resources take the **parent ID as the first argument**:
 
+For the underlying HTTP surface — every endpoint with the API key scope it requires — see the [Admin API endpoint index](../../../api-reference/admin-api/endpoints.md).
+
 ```typescript
 // Top-level
 const order = await client.orders.get('order_xxx')

package/dist/developer/upgrades/5.3-to-5.4.md

@@ -254,7 +254,7 @@ And run `bundle install`
 
 ### (Optional) Install Spree Multi Store
 
-[Multi-store](../multi-store/quickstart.md) features like multiple store management & custom domains were moved to a separate gem `spree_multi_store`.
+[Multi-store](../multi-store/quickstart.md) features like multiple store management & custom domains were moved to a separate gem [spree_multi_store](../multi-store/quickstart.md).
 
 If you rely on these features please run:
 

package/dist/developer/upgrades/5.4-to-5.5.md

@@ -122,7 +122,7 @@ This is a no-op on the default Database provider (there is no external index to
 
 #### Multi-store catalogs
 
-If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming `spree_multi_store` extension restores the full `Product has_many :stores` association on top of it.
+If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming [spree_multi_store](../multi-store/quickstart.md) extension restores the full `Product has_many :stores` association on top of it.
 
 For single-store deployments this is invisible; you can move on without touching `spree_products_stores` again.
 

package/dist/integrations/integrations.md

@@ -36,10 +36,3 @@ description: "Browse Spree's third-party integrations for payments, shipping, ta
 
 
   - [Klaviyo](marketing/klaviyo.md) — Klaviyo is a marketing automation platform that allows you to send email campaigns to your customers.
-
-
-## SSO, MFA & Social Login
-
-
-  - [Admin Panel SSO & MFA](sso-mfa-social-login/admin-dashboard.md) — Learn how to secure your Spree admin panel with SSO and MFA integration, using Microsoft Entra ID as an example.
-  - [Storefront SSO & Social Login](sso-mfa-social-login/storefront.md) — Enable customer-facing SSO and social login on your Spree storefront, using Microsoft Entra External ID as an example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.93",
+  "version": "0.1.94",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

package/dist/integrations/sso-mfa-social-login/admin-dashboard.md

@@ -1,57 +0,0 @@
----
-title: "SSO and MFA for the Admin Panel"
-sidebarTitle: "Admin SSO & MFA"
-description: "Learn how to secure your Spree admin panel with SSO and MFA integration, using Microsoft Entra ID as an example."
----
-
-Enterprise businesses require **Single Sign-On (SSO)** and **Multi-Factor Authentication (MFA)** to secure sensitive operations, maintain compliance, and simplify IT administration. For Spree Commerce, the **admin panel** is the heart of your business operations, which means securing access here is critical.
-
-## SSO providers
-
-There are many popular SSO providers, such as **Microsoft Entra ID**, **Okta**, **Ping Identity**, and **OneLogin**. Each provider may also offer multiple services under its ecosystem.
-
-For example, Microsoft’s SSO ecosystem includes:
-
-- **Entra ID (previously Azure Active Directory)** → secures your **Spree Commerce admin panel** for workforce users.
-- **Entra External ID (previously Active Directory B2C)** → secures your **Spree storefront** for customer-facing apps, with support for social logins like Google and Facebook.
-
-> **NOTE:** For the purposes of this article, we are using **Microsoft** as the example provider.
-
-## Why integrate SSO with MFA for the Admin Panel
-
-- **Used by staff, merchants, and operators**
-- **Integration with Entra ID** ensures employees can log in using their corporate credentials
-- Benefits include:
-  - Higher security
-  - Regulatory compliance (SOC2, HIPAA, GDPR)
-  - Simplified IT administration
-  - Better user experience with SSO
-- With Microsoft solutions, you can also enable **Multi-Factor Authentication (MFA)** or **passwordless options** (Windows Hello, FIDO2 keys) to further strengthen access security
-
-## Get Started with SSO and MFA
-
-Each SSO integration needs to be scoped individually. The integration plan depends on multiple factors, such as:
-
-- **Required SSO provider**
-  - Decide whether you’ll use Microsoft Entra ID, Okta, Ping Identity, OneLogin, or another vendor. Each provider offers different features, protocols, and integration options.
-- **SSO provider settings**
-  - Each provider has unique configuration details, such as OAuth endpoints, certificates, tenant IDs, and federation settings. You’ll need to gather these to complete integration.
-- **Existing or planned Spree customizations**
-  - Custom authentication flows, extended user models, or unique admin permissions may affect how SSO is integrated. These should be reviewed before implementation.
-- **Spree version**
-  - Compatibility matters. Integration strategies can differ depending on whether you’re on the latest Spree release.
-- **Use case: single tenant vs. multi-tenant**
-  - Single-tenant stores usually need straightforward workforce SSO. Multi-tenant or SaaS-style deployments may require isolated tenant directories and more complex provisioning.
-- **Identity governance requirements** (role-based access, just-in-time provisioning)
-- **User lifecycle management** (provisioning/de-provisioning)
-- **Security posture** (MFA enforcement, conditional access, passwordless policies)
-- **Compliance certifications required** (ISO, SOC2, HIPAA, PCI DSS)
-- **Traffic scale and performance** (concurrent users, global access, load balancing)
-- **Disaster recovery and redundancy** (failover strategies)
-- **Integration with third-party services** (analytics, CDPs, data warehouses)
-
-> **INFO:** Let's get in touch so we can scope your requirements and deliver this important integration for your project.
-
-
-  - [Book a Call](https://getvendo.com/book-a-demo/) — Schedule a call to explore the options and get your questions answered
-  - [Ask a Question](https://spreecommerce.org/get-started/) — Send us a message and share your thoughts

package/dist/integrations/sso-mfa-social-login/storefront.md

@@ -1,56 +0,0 @@
----
-title: "SSO and Social Login for the Storefront"
-sidebarTitle: "Storefront SSO & Social Login"
-description: "Enable customer-facing SSO and social login on your Spree storefront, using Microsoft Entra External ID as an example."
----
-
-Enterprise businesses benefit from offering **customer-facing SSO and social login** because it streamlines the shopping experience and improves conversions. Customers prefer using accounts they already trust instead of creating new ones.
-
-## SSO providers
-
-There are many popular SSO providers, such as **Microsoft Entra External ID**, **Auth0**, **Okta**, and **Ping Identity**. Each provider may offer several services with different target use cases.
-
-For example, Microsoft’s SSO ecosystem includes:
-
-- **Entra ID (previously Azure Active Directory)** → secures your **Spree Commerce admin panel** for workforce users.
-- **Entra External ID (previously Active Directory B2C)** → secures your **Spree storefront** for customer-facing apps, with support for social logins like Google and Facebook.
-
-> **NOTE:** For the purposes of this article, we are using **Microsoft** as the example provider.
-
-## Why integrate SSO and Social Login for the Storefront
-
-- **Used by shoppers**
-- Integration with **Entra External ID (B2C)** or other customer identity providers enables frictionless sign-ups and sign-ins
-- Benefits include:
-  - Reduced cart abandonment
-  - Faster checkout
-  - Higher conversion rates
-- Supports **social login options**: Google, Facebook, Amazon, Apple ID, Microsoft
-
-## Get Started with SSO and Social Login
-
-Each storefront integration must be scoped individually. Consider the following:
-
-- **Required SSO provider**
-  - Choose from Microsoft Entra External ID, Auth0, Okta, Ping Identity, or others. Your decision depends on features, ecosystem compatibility, and scalability needs.
-- **SSO provider settings, including identity providers**
-  - Each SSO platform has unique configuration settings (OAuth endpoints, certificates, client IDs). If you want to enable social logins, you’ll also need to configure providers like Google, Facebook, or Apple.
-- **Scope: social login only vs. SSO + social login**
-  - Decide whether you only want to add social login on top of Spree’s existing authentication or fully replace it with a unified SSO + social login solution.
-- **Existing or planned Spree customizations**
-  - Customized signup flows, checkout flows, or customer segmentation logic may impact integration design. These need to be factored in during scoping.
-- **Spree version**
-  - Ensure compatibility with your Spree version. Older projects may need adjustments to take advantage of newer identity management features.
-- **Identity governance requirements** (segmentation, customer role-based access)
-- **User lifecycle management** (account creation, deactivation, syncing)
-- **Security posture** (MFA for customers, adaptive login, fraud detection)
-- **Compliance certifications required** (GDPR, CCPA, PCI DSS)
-- **Traffic scale and performance** (millions of customer accounts, peak season load)
-- **Disaster recovery and redundancy** (failover, global availability zones)
-- **Integration with third-party services** (marketing automation, CDPs, analytics, loyalty programs)
-
-> **INFO:** Let's get in touch so we can scope your requirements and deliver this important integration for your project.
-
-
-  - [Book a Call](https://getvendo.com/book-a-demo/) — Schedule a call to explore the options and get your questions answered
-  - [Ask a Question](https://spreecommerce.org/get-started/) — Send us a message and share your thoughts