Shopware 6 has always provided two distinct RESTful surfaces for interacting with its e-commerce engine: the Store API and the Admin API. While both expose JSON endpoints over HTTP, they were designed with fundamentally different audiences, security models, and data scopes in mind. With the release of Shopware 6.7, this architectural boundary has been further hardened, standardized, and documented, making it essential for developers to understand exactly when and how to use each layer. Whether you're building a headless storefront, a mobile application, or a backend synchronization service, choosing the correct API prevents security vulnerabilities, context leakage, and performance bottlenecks.

Architectural Separation: Why Two APIs?

Shopware's dual-API design is rooted in a clear separation of concerns. The Admin API serves as the internal control plane for backend operations. It manages products, orders, customers, promotions, system configurations, and plugin states. Calls to this API assume a trusted environment where the caller possesses administrative privileges and operates outside the constraints of storefront validation logic.

Conversely, the Store API is explicitly engineered for customer-facing interactions. It handles product listings, shopping carts, checkout flows, account management, and personalized pricing calculations. Every Store API request runs through a strict context pipeline that enforces customer group restrictions, currency conversion, tax rules, shipping locations, and availability constraints. The two APIs do not share endpoints, nor do they share authentication contexts. This separation ensures that backend administrative actions cannot accidentally or maliciously bypass storefront business logic, and public-facing endpoints remain securely isolated from sensitive system data.

Authentication & Token Lifecycle

Authentication is the most critical differentiator between the two layers.

The Admin API uses a standard OAuth2 client credentials flow. Applications register via Administration > Apps to receive a client-id and client-secret. A token is requested at /api/admin/oauth/token, and subsequent requests require a Bearer <token> header. This token does not tie to a specific customer or storefront session; it grants application-level access to administrative resources. In Shopware 6.7, admin tokens are subject to stricter rotation policies and can be audited more granularly through the activity log.

The Store API relies on a storefront context token (sw-context-token). This token is generated by authenticating through /api/store-api/account/login or /api/store-api/context. It must be passed in every subsequent request via the sw-context-token HTTP header. Unlike admin tokens, the context token encapsulates the entire customer state: assigned group, currency, language, shipping/ billing addresses, tax preferences, and cart contents. In 6.7+, context tokens are automatically rotated after sensitive operations (like checkout or address changes) to prevent session fixation, and they include stricter expiration validation on the server side.

Attempting to use an admin token on a store endpoint (or vice versa) will result in a 401 Unauthorized or 403 Forbidden response. Shopware 6.7 also enforces CORS boundaries more rigidly, ensuring that frontend browsers cannot inadvertently leak admin credentials while still allowing legitimate storefront tokens to function across trusted domains.

Routing & Endpoint Organization

Each API lives in its own route namespace and follows distinct registration conventions:

  • Admin endpoints are prefixed with /api/admin. They are typically registered via Symfony routes decorated with routeScope="administration" or defined in plugin configuration files like administration.xml/storefront.xml under the admin provider. Route controllers often extend \Shopware\Administration\Framework\Routing\RoutingController patterns.

  • Store endpoints are prefixed with /api/store-api. They are registered using the modern StoreApiRouteRegistration service or via routes/store_api_routes.xml in a plugin. Shopware 6.7 has unified route registration under a single service interface, making custom endpoint discovery significantly more predictable.

Both APIs now share a centralized OpenAPI specification available at /swagger-ui/index.html. However, the Store API documentation emphasizes payload constraints (e.g., required address fields for checkout), while the Admin API documentation focuses on bulk operation capabilities and system configuration paths.

Context, Validation & Response Behavior

Both APIs utilize Shopware's context system, but they apply it differently:

  • The Admin context is backend-oriented. It bypasses storefront pricing calculations unless explicitly triggered. This allows administrators to manipulate prices, stock levels, or customer data without triggering customer-facing promotions or availability checks. Payloads are validated against administrative entity schemas, which are generally more permissive.

  • The Store context is strictly bound to the customer session and storefront rules. Every request triggers the full price calculation stack, tax resolution, shipping rule evaluation, and product availability checks. Payload validation uses Form or RequestPayloadSchema constraints tailored for public-facing safety. Invalid cart quantities, missing shipping addresses, or restricted customer group access will fail early with structured error responses.

Response structures also differ in intent. Admin endpoints often return raw entity collections optimized for bulk processing. Store endpoints return enriched payloads ready for UI rendering, including calculated prices, formatted availability status, and localized metadata.

Shopware 6.7 Improvements

Shopware 6.7 introduces several refinements that impact both APIs:

  • Stricter rate limiting on /api/store-api by default, configurable via rate_limit.store_api.enabled in local parameters. This mitigates brute-force login attempts and cart enumeration attacks.
  • Deprecation of legacy context tokens. The old context-token header is removed; only sw-context-token is accepted for storefront requests.
  • Enhanced OpenAPI typing with stricter request/response schema validation, reducing runtime parsing errors in custom integrations.
  • Improved error structure. Both APIs now return standardized JSON: { "status": 400, "title": "Bad Request", "detail": "...", "code": "FRAMEWORK__VALIDATION_ERROR" }.
  • Performance optimizations for high-traffic Store API routes using query caching and result projection pipelines.

Practical Code Examples

Obtaining & Using a Store Context Token (Shopware 6.7+)

POST /api/store-api/account/login HTTP/1.1
Host: your-domain.com
Content-Type: application/json

{
  "username": "[email protected]",
  "password": "securePassword123"
}

Use the returned sw-context-token for storefront operations:

GET /api/store-api/product-listing/default HTTP/1.1
Host: your-domain.com
sw-context-token: <returned-storefront-context-token>

Obtaining & Using an Admin Access Token

POST /api/admin/oauth/token HTTP/1.1
Host: your-domain.com
Authorization: Basic base64(<app-id>:<app-secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Use the returned bearer token for administrative operations:

GET /api/admin/product HTTP/1.1
Host: your-domain.com
Bearer: <returned-admin-access-token>

Decision Matrix & Best Practices

| Feature | Store API | Admin API | |--------------------------|------------------------------------|------------------------------------| | Purpose | Customer-facing, public endpoints | Backend management, internal apps | | Authentication | sw-context-token (session-bound) | OAuth2 client credentials | | Prefix | /api/store-api/ | /api/admin/ | | Context Sensitivity | High (group, currency, tax, cart) | Low (system-level overrides) | | CORS / Security | Strictly enforced for storefronts | Locked to admin route providers | | Ideal Use Case | Headless storefronts, mobile apps | ERP sync, bulk imports, plugins |

Best Practices in Shopware 6.7:

  • Never expose admin tokens to browsers or client-side code. Store API context tokens are safe for frontend use but must be transmitted over HTTPS only.
  • Always include sw-context-token in store requests; without it, pricing and availability defaults will be applied incorrectly.
  • Use Shopware's official SDK (shopware/shopware-sdk) for type-safe interactions and automatic token handling.
  • Monitor rate limits via X-RateLimit headers on store endpoints during peak traffic.
  • Keep OpenAPI specs synced by regenerating /swagger-ui/index.html after custom route implementations.

Conclusion

The Store API and Admin API in Shopware 6 are complementary but non-interchangeable layers of the platform's architecture. The Admin API empowers backend automation, data management, and system configuration, while the Store API delivers a secure, context-aware foundation for customer-facing commerce experiences. Shopware 6.7 has clarified this boundary through stricter token lifecycle management, unified route registration, enhanced rate limiting, and improved validation patterns. By understanding their authentication models, routing structures, and contextual constraints, you can architect integrations that are both secure and performant. Choose the Admin API for backend operations, reserve the Store API for storefront interactions, and leverage Shopware 6.7's refined boundaries to build resilient, future-proof e-commerce ecosystems.