Store-API Protection

For IT security, it is important that APIs are secure. Since we have transitioned many functions to the Store API for the B2B platform, we have developed tools to help you secure the API.

Field Protection in EntityDefinition

Similar to the ApiAware flag in Shopware, we introduced a field protection mechanism to manage context-specific access control.

While all fields are fully editable, specific fields are restricted to read-only access. This protection layer provides fine-grained control over field accessibility and has been applied systematically and consistently.

CustomerJsonReadProtected

Granular protection for specific paths within JSON fields (e.g., custom fields).

Parameter	Type	Descriptio
protectedFields	array	List of field paths to protect (e.g., ['customField.sensitiveData']).
excludeSalesRepresentatives	bool	Sales representative exemption flag.

Access Logic

• Fields not in protectedFields remain visible.

• Protected paths are hidden by default.

• Sales representatives may access protected paths when excludeSalesRepresentatives is enabled.

CustomerReadProtected

Controls entire field visibility for customer-related data.

Parameter	Type	Descriptio
excludeSalesRepresentatives	bool	If true, allows sales representatives to bypass restrictions.

Access Logic

• Access is denied by default.

• If excludeSalesRepresentatives is enabled, sales representatives receive access.

• Requires:

  • Valid customer session

  • Active B2B platform context

EmployeeJsonReadProtected

Path-based JSON field protection with employee permission system.

Parameter	Type	Descriptio
protectedFields	array	Protected JSON paths.
selfAllowed	bool	Self-access permission.
permissions	array	Required permissions.
selfRelatedField	string	Field for self-relation matching.

Access Logic

• JSON paths are filtered according to protectedFields.

• Permission checks are applied based on employee role.

• Self-access is granted when:

  • selfAllowed is true

  • The entity matches the current employee via selfRelatedField

EmployeeReadProtected

Field-level access control based on employee permissions and roles.

Parameter	Type	Descriptio
selfAllowed	bool	Allow employees to view their own data.
permissions	array	Required permissions to access the field.
selfRelatedField	string	Entity field to match against employee ID (default: 'id').

Access Logic

Access is evaluated in the following order:

1. Sales representatives → Full access

2. Admin employees → Full access

3. Self-access → Allowed when:

   • selfAllowed is true

   • Entity relates to current employee

4. Permission-based access → Granted when employee role contains required permissions

Store-API Route Protection

Certain routes are restricted by role; some may only be accessed by sales representatives, while others are intended exclusively for B2B employees.

When working within the Store API, this access control is not applied automatically and must be implemented explicitly within your own route logic.

We would like to provide you with a few lines of sample code that you can use as a ready-to-use example.

Route Annotations

We provide two custom route annotations for access control in the Shopware API. These annotations integrate with the B2B context system, which enforces user-type restrictions and permission-based access.

B2bPlatformContextRequired

Controls route access based on B2B user type and context.

Values:

• true (default) - Requires any valid B2B platform context (employee, sales representative, or B2B supervisor)

• 'onlyEmployee' - Restricts access to employees only

• 'onlySalesRepresentative' - Restricts access to sales representatives only

Exception Thrown:

• B2bPlatformContextException (HTTP 403) - "Customer does not have b2b platform access"

• InsufficientEmployeePermissionException (HTTP 403) - When 'onlyEmployee' is set and user is not an employee

B2bPlatformPermission

Enforces fine-grained permission checks based on employee roles.

Value: Array of required permission strings (e.g., ['admin'], ['order'])

Exception Thrown:

• InsufficientEmployeePermissionException (HTTP 403) - Includes list of required permissions in error message