External system integrations are a cornerstone of modern e-commerce architecture. Whether you’re synchronizing inventory across warehouses, pushing customer segments into an ERP, or triggering automated fulfillment workflows, secure and programmatic access to your commerce platform is non-negotiable. Shopware 6.7 continues to refine its API authentication model, cementing OAuth 2.0 as the standard for external integrations. While many developers initially associate OAuth with storefront endpoints, configuring an integration correctly grants controlled, auditable access to administrative resources—provided you understand how roles, scopes, and token lifecycle management intersect in Shopware 6.7+.

Why OAuth 2.0? The Architecture Behind Integration Security

Earlier Shopware versions relied heavily on API context tokens or basic authentication for integrations, which posed security and scalability challenges as systems grew more distributed. Shopware 6.7 standardizes on the OAuth 2.0 Client Credentials flow. This design pattern is purpose-built for machine-to-machine communication: no user interaction is required, credentials are validated strictly server-side, and access can be scoped to precise administrative permissions.

When you create an integration in the Admin panel, Shopware generates a unique client ID and client secret pair that serve as your OAuth application credentials. The architectural advantage lies in how Shopware maps these credentials to Access Rights (roles). Unlike traditional API keys that often grant blanket access, integrations inherit CRUD permissions based on their assigned role configuration. This means you can create read-only, write-specific, or highly specialized integrations without exposing your entire administration interface to external services.

Creating and Configuring Your Integration

The setup process is straightforward but demands precision. Navigate to Store > Integrations in your Shopware 6 Admin dashboard and click Create. Fill out the Basic Data section with a descriptive name and optional technical documentation link. Under Advanced Data, ensure “Generate access token” remains checked—this triggers the backend registration of your OAuth client against Shopware’s authentication service.

Once saved, you’ll receive your Client ID and Client Secret. Treat these like database credentials: never commit them to version control, and rotate them immediately if a leak is suspected. The critical next step is role assignment. In the Access Rights tab, Shopware 6.7 presents a hierarchical permission tree mapped directly to API controllers. Here, you define exactly which administrative endpoints the integration can reach. For example, enabling “Product” grants access to /api/product, while disabling it blocks all product-related administrative calls. You can mix permissions across Sales Channels, Customers, Orders, Documents, or custom plugin entities.

A common architectural mistake is over-provisioning permissions during initial setup. Follow the principle of least privilege: start with read-only access for integration testing, then incrementally grant write capabilities only when workflow requirements demand it. Shopware 6.7 also introduces improved audit logging for integration API calls, making it significantly easier to track which endpoints your service accessed, payload sizes, and response statuses across time.

The Token Exchange Flow

OAuth integrations do not use client credentials directly in API requests. Instead, you exchange them for a short-lived access token via Shopware’s centralized authentication endpoint. The route is consistently /api/oauth/token across all Shopware 6.7 installations. This endpoint accepts POST requests with the following form parameters:

  • grant_type: Must be exactly client_credentials
  • client_id: Your integration’s registered client ID
  • client_secret: Your integration’s registered secret

Upon successful validation, Shopware returns a JSON response containing an access_token, expires_in (typically 3600 seconds), and the token type. This access token must be included in all subsequent API requests via the Authorization: Bearer <token> header. Importantly, tokens are bound to the integration’s role matrix at generation time. If you modify permissions later, existing valid tokens retain their original scope until expiration. You must request a fresh token after role modifications if immediate access changes are required.

Implementation Example

Below is a production-ready PHP snippet demonstrating the token acquisition and API call workflow compatible with Shopware 6.7+:

<?php
// Step 1: Exchange credentials for an OAuth access token
$tokenEndpoint = 'https://your-shop.example.com/api/oauth/token';
$credentials = [
    'grant_type'    => 'client_credentials',
    'client_id'     => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET'
];

$ch = curl_init($tokenEndpoint);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($credentials),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded']
]);

$response = json_decode(curl_exec($ch));
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200 || !isset($response->access_token)) {
    throw new RuntimeException('OAuth token request failed: ' . ($response->error ?? 'Unknown error'));
}

// Step 2: Call Admin API route with the bearer token
$apiEndpoint = 'https://your-shop.example.com/api/product';
$apiCh = curl_init($apiEndpoint);
curl_setopt_array($apiCh, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $response->access_token,
        'Content-Type: application/json',
        'Swag-Session-Id: ' . session_id() // Optional: preserves context if needed
    ],
    CURLOPT_TIMEOUT        => 30
]);

$products = json_decode(curl_exec($apiCh));
curl_close($apiCh);

This pattern applies to any Admin API route. Just replace the base URL and adjust HTTP methods (GET, POST, PATCH, DELETE) based on the target endpoint’s OpenAPI specification. Shopware 6.7 enforces strict CORS and CSRF protections on OAuth endpoints, so always use HTTPS and validate HTTP status codes before parsing response bodies.

Lifecycle Management & Security Hardening

Access tokens expire after one hour by default in Shopware 6.7. Rather than making frequent token requests, implement a local caching strategy with a safety margin (e.g., refresh when remaining lifetime drops below 600 seconds). Store secrets and tokens in environment variables or a dedicated secret manager—never in configuration files or code repositories.

Beyond role scoping, Shopware 6.7 supports IP restriction for integrations. Under the Advanced Data tab, you can whitelist specific server IPs that are allowed to request tokens from your OAuth endpoint. This mitigates credential leakage risks even if secrets are partially exposed. Additionally, monitor failed token requests in your access logs; sudden spikes often indicate configuration drift, environment mismatches, or unauthorized probing.

When migrating from older Shopware versions, note that legacy API context tokens are fully deprecated in favor of this unified OAuth flow. Ensure your integration scripts are updated to handle HTTP 401/403 responses gracefully and implement automatic retry logic with exponential backoff for transient network instability. Also verify that custom entities created via plugins expose their routes under the allowed role matrix, as Shopware 6.7 tightly binds plugin API endpoints to core permission tables.

Final Thoughts

Implementing OAuth-based integrations in Shopware 6.7 transforms how external systems interact with your commerce platform. By leveraging client credentials, precise role mapping, and secure token management, you gain enterprise-grade API access without compromising store security. As e-commerce ecosystems grow more distributed and compliance requirements tighten, treating integration configuration as a foundational architectural decision—rather than an afterthought—will save considerable debugging time and reduce surface area for vulnerabilities. With Shopware 6.7’s hardened OAuth implementation, unified routing layer, and improved audit capabilities, you’re equipped to build resilient, scalable, and fully traceable system connections that stand the test of future framework updates.