Permissions explained

What access Conviro gets to your store, why, and which admin permissions the module adds. Plan §20 item 5. Source: AiChat/Service/Auth/IntegrationManager.php, AiChat/etc/acl.xml, AiChat/etc/webapi.xml, apps/api/src/modules/magento/magento-read-api.ts, apps/api/src/modules/magento/magento-connect.service.ts; read 2026-09-25.

1. The "Conviro AI Chat" Magento integration (REST, used by Conviro)

Connecting creates one integration under System › Extensions › Integrations named Conviro AI Chat (contact [email protected]). Conviro calls your REST API with this integration's OAuth 1.0a credentials. The module grants exactly the resources below each time the store registers (Save Config, setup wizard, Reconnect, the automatic re-registration after an upgrade), which also repairs an integration whose permissions were changed by hand.

The Conviro read API (1.4.0)

Since 1.4.0 the integration holds none of Magento's own catalog, sales, customer, cart or store resources. Those resources also open Magento's write routes: measured on Magento 2.4.7-p4 (dev/tests/acl-reach.php), the set 1.3.x granted reached 61 non-GET core routes — creating, changing and deleting products, prices and stock, sixteen cart routes including place order — plus an unfiltered customer and cart search. Instead the module serves its own read-only REST routes under /rest/V1/conviro/… (and /rest/<store code>/V1/conviro/…, AiChat/etc/webapi.xml) and the integration is granted only those:

The order-listing permission (1.5.0, unreleased). Conviro_AiChat::api_customer_orders ("A verified shopper's own orders (read)") mirrors no core route and grants nothing else: two GET routes that answer only for a signed-session binding the store itself created, only that binding's customer's orders, only in its store view (or website, with Orders a verified shopper sees = website), and only statuses the storefront shows. It is least privilege by switch: the module adds it to the integration's grant only while Enable signed customer identity and Show verified shoppers their own orders are on for at least one website, and the next registration (Save Config, Reconnect, Repair access) removes it when they are off everywhere. A store that never switches My orders on never holds it. When it is missing although My orders is on, the Customer Experience & Identity card shows Order listing permission missing (Turkish admin: Sipariş listeleme izni eksik) with Repair access, which registers the store again so Magento grants it (Integration Health). Conviro then also sees Magento answer 401 on that route and shows the same warning in its dashboard.

Each route answers exactly what Magento's core route of the same path (without conviro/) answers — same service contract, same data — measured on 2.4.7-p4: every read Conviro makes, answered by the Conviro route and by the core route, compared field by field (dev/tests/oauth-roundtrip.sh). The stock item inside a product answer (extension_attributes.stock_item, which Magento shows only to holders of Magento_CatalogInventory::cataloginventory — a resource that also opens the stock WRITE route) is shown on the module's product routes to holders of Conviro_AiChat::api_catalog (plugin ReadApiStockItemVisibility, REST GET on those routes only). Conviro also reads two core routes that need no grant at all: products-render-info (storefront price) and directory/currency.

Magento itself always records Magento_Backend::admin for an integration role; with it an integration can read GET /V1/modules (the list of enabled module names) — true of every Magento integration. Conviro reads that list only to learn whether MSI is installed on a store whose module predates the ping. The parent node Conviro_AiChat::api is granted too; it guards only the ping route (Magento stores an allow or deny for every resource, so the parent grants none of the leaves).

The module announces the read API when it registers (readApi: conviro-v1), and Conviro then reads the store only through these routes. A store upgraded from 1.3.x keeps the core resources it already had until Conviro confirms the read API in its answer, then they are removed in the same registration — so nothing Conviro reads today stops working if the upgrade happens while Conviro cannot be reached. While they are still held, the Integration Health card's Authentication row says so (Warning). If the module is downgraded below 1.4.0 (or disabled) the Conviro routes disappear. Conviro notices it without reading any error text — Magento translates "Request does not match any route." into the store's language: when a Conviro route answers 404 it asks conviro/ping once (then remembers the answer for ten minutes). A ping answer means the 404 was real ("no such product / order") and is used as it is; a ping 404 means the read API is gone — Conviro reads the same thing through the core route and from then on only the core routes. The downgraded module's own registration (it does not announce the read API) restores the core resources and clears the read API on Conviro's side too.

**Only while Order-action assistance is on** (capabilities/allow_order_actions, off by default; wizard step 6), and removed again when it is switched off — Magento's own write routes, with their parent chain Magento_Sales::sales › sales_operation › sales_order › actions (measured: these reach exactly the three routes below plus the read-only checkout-agreements list):

On Adobe Commerce only, and only while order-action assistance is on, the module also requests Magento_Rma::magento_rma (returns: POST /V1/returns and the RMA reads) and Magento_NegotiableQuote::manage (B2B quote requests) with their parent chains, where the installation's ACL tree has them (Magento Open Source has neither). Magento_Cart::manage is no longer requested at all: a B2B quote request, which first creates a customer cart, therefore becomes a task for your team, like any request the store has no API for. The Adobe Commerce resources follow Adobe's webapi.xml; they are unit-tested, not run on Adobe Commerce (no licence).

These writes happen only through Conviro's AI action policy (a customer confirms, and by default a team member approves) or when a staff member acts in the Conviro dashboard — see AI permissions and the action policy.

Not requested. Any Magento catalog, inventory, sales, customer, cart, store or config resource (see above), attribute metadata (which is why the module sends attribute labels itself), sales rules / coupons, customer addresses, invoices, credit memos.

No store-wide bearer mode. The module does not switch on Magento's Allow OAuth Access Tokens to be used as standalone Bearer tokens (enable_integration_as_bearer). A store still on the legacy bearer connection works through a narrow plugin scoped to this one integration (Architecture); it answers with the same least-privilege role. 1.3.x did switch it on, and the upgrade leaves it as it was: see Upgrade guide to turn it off, or use the Turn off store-wide bearer tokens button on the Integration Health card (Integration Health).

You can inspect the grant in the diagnostics bundle (integration.aclResources, integration.missingResources); the Integration Health card's Authentication row turns to Action required when a resource is missing (run bin/magento setup:upgrade if the Conviro_AiChat::api_* resources are unknown — they come with 1.4.0).

2. Magento admin permissions added by the module

Administrators with All resources get both. For a custom role see the upgrade guide.

1.5.0 (unreleased): signed customer identity. One new admin resource, Conviro Reset identity (advanced security action) (Conviro_AiChat::identity_reset, a child of Conviro Setup; owner decision 2026-09-27). Reset identity needs it and Conviro Setup. On upgrade, every role that already has rules and none for this resource gets an explicit deny (Setup/Patch/Data/DenyIdentityResetToExistingRoles), because Magento would otherwise let it inherit Conviro Setup; roles with All resources keep it. Grant it deliberately under System > Permissions > User Roles > Role Resources. The other admin actions use the two resources above:

The four identity switches (identity/enabled, my_orders_enabled, order_scope, guest_verification_enabled) need Conviro_AiChat::setup to change, like the AI capability switches; with Conviro AI Chat only they are read-only. The storefront route GET /conviro/identity/bootstrap needs no admin permission — it answers only the signed-in shopper's own session. Not yet measured with admin-permissions.sh (needs the Docker stack; the script checks the Reset identity resource too — a Conviro Setup admin without it gets no button, no impact page and a forged POST changes nothing).

The Conviro URLs (general/api_url, general/app_url, general/docs_url) accept only https:// addresses on conviro.io — from any admin and from bin/magento config:set; the read-only fields post nothing back. A private or development deployment sets another URL in app/etc/env.php (Configuration reference). Measured with dev/tests/admin-permissions.sh (a role with Conviro AI Chat only).

3. The Conviro API key the module holds

magento:module covers exactly what the module calls: tenant-info, module-version, register-store, store-mapping, disconnect-store, the events endpoint, the two admin stats cards and the lead-form list — no conversation read, no knowledge-base write. Module 1.5.0 (unreleased) also calls POST /api/magento/identity-keys (the store's public identity key — magento:module only, so a hand-pasted key without that scope cannot register it), GET /api/magento/identity-status and POST /api/magento/identity-test (either scope; 10 tests an hour per store). kb:write covers the same Magento routes (and more of the public API); chat:read covers the module-version check, the stats cards and lead forms. A connect-minted key registers only its own store; a disconnected store is registered again only with a key created after the disconnect (Reconnect and disconnect). 600 / minute leaves room for the outbox, which sends up to 50 events per batch.

Connecting again with the wizard gives earlier keys this flow minted for the same store 24 hours before they expire. Disconnecting from Magento revokes a key the connect flow minted; a pasted key is not revoked — revoke it yourself in the Conviro dashboard if you no longer need it.

Your Conviro API key (any valid key) is also the Composer password for repo.conviro.io (Installation).

4. Conviro dashboard roles