# Store-API Protection

## 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).

<table><thead><tr><th>Parameter</th><th width="100">Type</th><th>Descriptio</th></tr></thead><tbody><tr><td><code>protectedFields</code></td><td>array</td><td>List of field paths to protect (e.g., <code>['customField.sensitiveData']</code>).</td></tr><tr><td><code>excludeSalesRepresentatives</code></td><td>bool</td><td>Sales representative exemption flag.</td></tr></tbody></table>

**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.

<table><thead><tr><th>Parameter</th><th width="100">Type</th><th>Descriptio</th></tr></thead><tbody><tr><td><code>excludeSalesRepresentatives</code></td><td>bool</td><td>If true, allows sales representatives to bypass restrictions.</td></tr></tbody></table>

**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.

<table><thead><tr><th>Parameter</th><th width="100">Type</th><th>Descriptio</th></tr></thead><tbody><tr><td><code>protectedFields</code></td><td>array</td><td>Protected JSON paths.</td></tr><tr><td><code>selfAllowed</code></td><td>bool</td><td>Self-access permission.</td></tr><tr><td><code>permissions</code></td><td>array</td><td>Required permissions.</td></tr><tr><td><code>selfRelatedField</code></td><td>string</td><td>Field for self-relation matching.</td></tr></tbody></table>

**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.

<table><thead><tr><th>Parameter</th><th width="100">Type</th><th>Descriptio</th></tr></thead><tbody><tr><td><code>selfAllowed</code></td><td>bool</td><td>Allow employees to view their own data.</td></tr><tr><td><code>permissions</code></td><td>array</td><td>Required permissions to access the field.</td></tr><tr><td><code>selfRelatedField</code></td><td>string</td><td>Entity field to match against employee ID (default: <code>'id'</code>).</td></tr></tbody></table>

**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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.b2b-sellers.com/b2b-platform/developer-guide/first-steps/store-api-protection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.