# Magento Integration & Permissions (MerchPilot VNext)

This document defines the minimal Magento REST API scope and minimal Integration ACL scope required by MerchPilot VNext.

MerchPilot uses Magento REST API with Magento Integration credentials. No Magento module installation is required.

## Authentication input formats

MerchPilot Stores uses 4 OAuth1 credential fields:

1. `consumer_key`
2. `consumer_secret`
3. `access_token`
4. `access_token_secret`

This matches Magento OAuth1 integration credentials and works when `Allow OAuth Access Tokens to be used as standalone Bearer tokens` is set to `No`.

## Section A - Required REST Endpoints

### Read endpoints (sync and apply/rollback state)

| Method | REST Path | Purpose | Why Needed | Access |
| --- | --- | --- | --- | --- |
| `GET` | `/rest/V1/store/storeConfigs` | Read store configuration and validate token/base URL | Connection test and environment sanity check | `READ` |
| `GET` | `/rest/V1/products` | Product snapshot by `searchCriteria` | Sync product catalog fields and visibility/status checks | `READ` |
| `GET` | `/rest/V1/categories/list` | Category list by `searchCriteria` | Sync category metadata (`id`, `parent_id`, `name`, `is_active`, `path`, `level`) | `READ` |
| `GET` | `/rest/V1/products` with `category_id` filter | List products in category and derive positions from `extension_attributes.category_links` | Sync category positions | `READ` |
| `GET` | `/rest/V1/products/{sku}` | Read current product state before writes | Idempotent apply checks and rollback conflict checks | `READ` |

### Write endpoints (apply and rollback)

| Method | REST Path | Purpose | Why Needed | Access |
| --- | --- | --- | --- | --- |
| `PUT` | `/rest/V1/products/{sku}` | Update product payload (category links and/or price fields) | Apply planned changes and restore snapshots on rollback | `WRITE` |

### SearchCriteria examples

Products (incremental sync):

```text
GET /rest/V1/products
?searchCriteria[filter_groups][0][filters][0][field]=updated_at
&searchCriteria[filter_groups][0][filters][0][value]=2026-02-22 00:00:00
&searchCriteria[filter_groups][0][filters][0][condition_type]=gt
&searchCriteria[sortOrders][0][field]=updated_at
&searchCriteria[sortOrders][0][direction]=ASC
&searchCriteria[currentPage]=1
&searchCriteria[pageSize]=100
```

Categories (checkpoint by id):

```text
GET /rest/V1/categories/list
?searchCriteria[filter_groups][0][filters][0][field]=entity_id
&searchCriteria[filter_groups][0][filters][0][value]=200
&searchCriteria[filter_groups][0][filters][0][condition_type]=gt
&searchCriteria[sortOrders][0][field]=entity_id
&searchCriteria[sortOrders][0][direction]=ASC
&searchCriteria[currentPage]=1
&searchCriteria[pageSize]=100
```

## Section B - Minimal ACL Permissions

Grant only the permissions required by the endpoints above. In Magento Admin (Integration Resource Access), use:

1. `Catalog > Inventory > Products`
Reason: read products and write product updates for apply/rollback.

2. `Catalog > Categories`
Reason: read category tree/list and derive category links used in payload checks.

3. `Stores > Settings > Configuration` (read-only scope in practice)
Reason: read `/store/storeConfigs` for connection test only.

Optional ACL resource IDs (version-dependent, for technical admins):
- `Magento_Catalog::products`
- `Magento_Catalog::categories`
- `Magento_Catalog::catalog`
- `Magento_Config::config`

MerchPilot does not require permissions to modify:
- Checkout or payment flow
- CMS content or blocks/pages
- Customer accounts

## Section C - Security Model

- Integration credentials are created in Magento Admin: `System > Extensions > Integrations`.
- Credentials are stored encrypted at rest in MerchPilot (`MERCHPILOT_ENC_KEY`, AES-256-GCM).
- Passwords are never stored by MerchPilot.
- API calls use retry/backoff and request logging for traceability.
- Apply flow snapshots current state before writes.
- Rollback restores from snapshots and is idempotent.
- Audit logs track user/store actions and run context.

### Security Summary

MerchPilot connects using scoped Magento Integration credentials, stores credentials encrypted at rest, applies only supported catalog changes via product update endpoint (category links and price fields in VNext), snapshots state before writes, and supports rollback and audit logging for safe operations.

## Section D - User Connection Checklist

1. Create an Integration in Magento Admin (`System > Extensions > Integrations`).
2. Assign only required ACL resources listed in Section B.
3. Activate the Integration and approve access.
4. Copy Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
5. In MerchPilot, open `Stores`, enter store `Base URL` and all 4 credential fields, then save.
6. Click `Test Connection`.
7. Run initial sync (`products`, `categories`, `category positions`).

Expected success:
- HTTP `200` from `/rest/V1/store/storeConfigs`
- MerchPilot store status remains `active`
- Last test message shows success with HTTP code

Common errors:
- `401 Unauthorized`: invalid/expired token, invalid OAuth1 signature, or wrong website base URL.
- `403 Forbidden`: ACL permissions missing for one or more required resources.
- `404 Not Found`: wrong base URL path/rewrite, incorrect `/rest` exposure.
- Timeout / network error: firewall, DNS, TLS, or upstream connectivity problem.

Safe revocation:
1. Disable or delete the Integration in Magento Admin.
2. In MerchPilot, rotate credentials or disable the store.
3. Re-run connection test to confirm revocation.

## Section E - Implementation Helper (UI)

MerchPilot includes an in-app page:
- `GET /app/connection-guide`
- Displays required endpoints, ACL scope, security summary, and checklist
- Includes a quick `Test Connection` action for selected store
- Shows last status and last test message for selected store