Shopware 6.7 represents a mature turning point for developers building custom integrations, headless storefronts, or ERP connectors. While earlier releases allowed flexible authentication methods, version 6.7 officially standardizes OAuth 2.0 as the primary mechanism for external API communication. This shift isn't merely a compliance update; it fundamentally changes how credentials are managed, scoped, and revoked across your commerce ecosystem. Understanding this transition is critical for architects aiming to build resilient, future-proof applications that align with Shopware's security roadmap.

Why OAuth2 Replaces Legacy Authentication in 6.7

Historically, many developers relied on Basic HTTP authentication or long-lived access keys for API calls. While convenient, these approaches store static secrets, complicate permission management, and increase exposure to credential leakage. Shopware 6.7 addresses these vulnerabilities by embedding a hardened OAuth 2.0 server directly into the platform's core routing and security layer. The built-in implementation leverages the League OAuth2 library but extends it with Shopware-specific adapters for multi-store context resolution, scope inheritance, and encrypted client storage.

By default, Basic authentication is now deprecated for storefront-facing requests, and system configurations that previously accepted static API keys require migration to OAuth clients. This enforces a standardized token lifecycle: short-lived access tokens paired with refresh tokens eliminate the need to persist credentials in environment variables, CI/CD pipelines, or frontend storage. Additionally, Shopware 6.7 introduces granular scope validation at the routing level, meaning every endpoint request is audited against registered client permissions before execution.

Client Registration & Scope Management

Before exchanging tokens, you must register an OAuth client within the Administration panel. Navigate to Settings > API Authentication or your specific sales channel configuration. Here, Shopware 6.7 presents a refined interface for generating client_id and client_secret pairs. Unlike earlier versions where scopes were applied globally during installation, 6.7 allows you to define permission boundaries at the client level.

When creating a client, you can assign explicit scopes such as write:product, read:order, checkout:cart, or admin:system-config. These scopes map directly to Shopware's routing filters and entity access controls. Attempting to request a scope that isn't granted will immediately fail during the token exchange phase. This principle of least privilege drastically reduces the blast radius if credentials are compromised, as the attacker gains only the permissions explicitly assigned during registration.

Choosing the Right OAuth Flow

Shopware 6.7 supports two primary flows out-of-the-box:

  1. Client Credentials Flow: Designed for server-to-server integrations where no human interaction occurs. The application presents its credentials directly to /oauth2/token and receives an access token suitable for background jobs, inventory syncs, or custom middleware.
  2. Authorization Code Flow with PKCE: Recommended for storefront applications, PWAs, or mobile clients. It ensures secure interactive authentication while protecting authorization codes from interception. The addition of PKCE (Proof Key for Code Exchange) in 6.7 prevents authorization code injection attacks without requiring a client secret on the frontend.

Both flows issue access tokens that expire after a configurable window (defaulting to 3,600 seconds). Refresh tokens are issued alongside them but follow rotation policies to mitigate replay risks. Shopware 6.7 enforces HTTPS strictly during token exchange and requires redirect URIs to be whitelisted in the client configuration for interactive flows.

Authentication Lifecycle Explained

When your application needs to call a protected endpoint, the process follows a predictable sequence:

  1. Token Request: Send a POST request to /oauth2/token with grant_type, credentials, and requested scopes.
  2. Validation: Shopware verifies the client exists, checks scope alignment, validates redirect URIs (if applicable), and confirms HTTPS compliance.
  3. Token Issuance: Upon success, return a JSON payload containing access_token, expires_in, token_type, and refresh_token.
  4. API Usage: Attach the access token via Authorization: Bearer <token> for subsequent requests. Shopware's middleware decrypts the JWT-style token, extracts scope claims, and validates entity-level permissions.
  5. Refresh Cycle: Before expiration, call /oauth2/token with grant_type=refresh_token. Shopware 6.7 rotates refresh tokens automatically, invalidating the previous one to prevent reuse attacks.

Code Example: Token Exchange & Refresh (Shopware 6.7+)

# Step 1: Obtain Access Token (Client Credentials)
curl -X POST https://your-store.com/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=sw67_client_abc123" \
  -d "client_secret=sk_live_xYz9QrT4wVnMkLp0JhGf" \
  -d "scope=write:product read:order"

# Step 2: Refresh Token (Automatic Rotation Enabled)
curl -X POST https://your-store.com/oauth2/token \
  -d "grant_type=refresh_token" \
  -d "client_id=sw67_client_abc123" \
  -d "client_secret=sk_live_xYz9QrT4wVnMkLp0JhGf" \
  -d "refresh_token=rft_oldTokenValue_xyz789"

Note: In production environments, always cache access tokens locally and implement exponential backoff during refresh. Shopware 6.7 rejects malformed scope strings or unregistered clients with a 401 Unauthorized response containing descriptive error codes like invalid_client or unsupported_grant_type. Never log full token payloads or secrets in application logs; use Shopware's audit system instead.

Security Hardening Checklist for 6.7+

  • Enforce HTTPS at the web server and Shopware configuration level.
  • Restrict redirect URIs during client creation to prevent open redirect vulnerabilities.
  • Rotate client_secret periodically via the Administration panel.
  • Monitor authentication failures through Store > Log & Audit to detect brute-force attempts.
  • Separate clients per environment (development, staging, production) to isolate scope leakage.
  • Disable automatic credential fallback in custom plugins by implementing Shopware's OAuth2TokenValidator interface.

Conclusion

Migrating to OAuth 2.0 in Shopware 6.7 transforms API security from a fragile dependency into an architectural advantage. By leveraging scoped tokens, automated refresh cycles, and standardized flows, developers can build resilient integrations without compromising on performance or maintainability. As Shopware continues refining its headless commerce capabilities, mastering OAuth authentication will remain essential for any team shipping modern storefronts, fulfillment pipelines, or multi-channel sync systems. Configure your clients thoughtfully, enforce scope boundaries, and future-proof your commerce stack today.