Customer identity runbook — "why doesn't it work?" in 30 seconds

1.5.0 (unreleased). For the admin card and dashboard section as built on 2026-09-27 (branches feat/magento-1.5.0-customer-hub, feat/magento-1.5.0-p34-module, feat/magento-1.5.0-p34-ui, and the Phase 5 module branch feat/magento-1.5.0-p5-module; not merged, not deployed). The Magento card opens with a first-blocker line that names the first failing gate of the table below (unit-tested, not yet run on a real store); the same line in the Conviro dashboard is built on the backend branch feat/magento-1.5.0-customer-hub (Phase 5 P5-14 afb631fc, unit-tested, not deployed). What the feature is: Signed customer identity and My orders.

Nothing you look at here shows a customer's data or a secret: the card, the dashboard section, Test identity bridge and the diagnostics bundle carry switch states, key ids (public), times, counts and closed-set reason words only.

The 30-second check

Open Stores › Settings › Conviro Setup (or Stores › Configuration › Conviro › AI Chat, group Signed Customer Identity) and read the first line under the card's title: First blocker: … names the first gate of the table below that fails, what is wrong and the fix, and its Runbook link opens the matching row here. The line checks this store first (it is on the page at once); a moment later, when Conviro has answered, it is replaced by the line for both sides. If Conviro cannot be reached, this store's first blocker still shows, or the line says Conviro's side is unchecked. The Integration Health summary line (Customer identity: …) links to the same row.

The gates, in the order the card checks them — the first one that fails is the cause; reading the card top-down by hand gives the same answer:

Gates 9–12 count only while Show verified shoppers their own orders is on for a website. When no gate fails the line says Nothing blocks signed customer identity…; then:

• Test identity bridge — a red step's line says the fix (steps);
• Card › At Conviro › Activity — failures with a top reason: what each reason means.

All green and a shopper still is not verified? Then the cause is on the shopper's side: the storefront checklist.

When the card is all green

• Is the shopper signed in in that store view, and did they open the chat? The store is asked only then, never on page load.
• Is the page rendered by Magento (Luma / Hyvä) with this release's loader? Click Check storefront on Integration Health (Storefront widget row); after an upgrade, deploy static content and flush caches. Headless / PWA frontends on another origin cannot use signed identity (Headless).
• Does a CDN, Varnish rule or proxy cache /conviro/identity/bootstrap? Many replayed failures say so (fix).
• Does the page run on the store view's configured secure base URL (not a CDN host, not www. vs. bare domain, not http)? The bootstrap refuses other origins (bootstrap answers).
• Is a person from your team handling the chat? Order cards are answered by the bot only.

In the browser's network tab (your own test account only): GET /conviro/identity/bootstrap should answer 200. Never copy its answer, the widget's requests or your cookies into a support ticket — the answer contains a signed customer id.

What the shopper saw → where to look

In the Conviro dashboard

Integrations › Magento › store card › Customer identity (owner or admin): the same switch and key states from Conviro's side, warnings with their fix (Order listing permission missing in Magento, A store view … is not mapped, The identity key is older than 180 days, The store's clock differs…, The store has not announced the identity bridge), and 7 / 30-day counts: verified conversations, verifications succeeded / failed by reason, My orders requests and reads (loaded, empty, unavailable, refused), the estimated p95 read time, handoffs. Counts only — no customer, session or order id.

Rotating the identity key

Routine (the card advises it after 180 days): click Rotate identity key (needs Conviro Setup), or run bin/magento conviro:identity:rotate-key. The card then shows the new key registered and "the previous key stays valid until …" (5 minutes). Run Test identity bridge. Nobody is signed out: shoppers verified with the old key keep it for the rest of their 15 minutes.

If you think the store's secret key was exposed (someone had your database and app/etc/env.php): click Reset identity on the card. It is an advanced security action (owner decision 2026-09-27): the admin needs both Conviro Setup and the dedicated permission Conviro Reset identity (advanced security action) (Conviro_AiChat::identity_reset, see Permissions). Roles that existed before 1.5.0 do not get it on upgrade; grant it deliberately under System > Permissions > User Roles. (Unit-tested; Conviro's side is built on feat/magento-1.5.0-reset, not deployed; the two have not run together yet — the Docker and Postgres runs are listed in the plan.)

1. Impact page. The card first shows what the reset affects: the websites and store views whose shoppers this installation signs for (names and codes; websites with signed identity off are counted as not affected), the current key id (first 8 characters), the live verified-shopper bindings in Magento, and the line Not affected: the Conviro connection (OAuth / API key), webhooks, orders and the event outbox, and any other store connected to Conviro. Conviro does not report how many verified sessions it holds; the page says so (each one started from a binding of the last 16 minutes).
2. Confirm. Type RESET (the same in every language) and click Reset identity now. The confirmation is valid for 10 minutes, for you only, and once. A POST without it (a bookmark, a forged form, another admin's page) changes nothing and is written to the audit table.
3. What happens. The store writes a reset request id and marks the reset pending before it calls Conviro — from that moment it signs nothing. Conviro revokes every identity key of this store's integration, ends every verified shopper session and open verification — and nothing else: not the OAuth connection, webhooks, orders, other stores of your workspace or other workspaces. Only when Conviro confirms that exact request does the store delete its old key, revoke its live bindings, and register a new key. Shoppers are verified again the next time they open the chat. Then run Test identity bridge.

What the card can say afterwards:

• Identity reset: Conviro revoked … — done.
• The result is unclear — it is safe to try again (tr: Sonuç belirsiz — güvenle tekrar deneyin): no answer, a timeout, a dropped connection, a Conviro error (5xx) or the network protection answered. Nobody knows yet whether Conviro reset it, so the old key is kept but not used and signed identity stays off (the card shows reset pending; Save Config and Rotate identity key wait for it). Click Reset identity again: the retry reuses the same request id and Conviro applies it only once — a late duplicate can never revoke the new key.
• Identity was not reset: … Nothing changed in this store — Conviro refused it outright (bad request, API key, store binding, not registered, rate limit). The store signs as before; fix the cause and try again.
• Identity was not reset on this retry … — Conviro refused a retry; an earlier attempt may already have reset it, so signed identity stays off until a retry is confirmed. Fix the cause (usually the connection: Reconnect) and click Reset identity again.
• The Conviro backend does not support Reset identity yet — nothing changed; follow the manual steps below.
• Identity was reset at Conviro, but the new key could not be registered — signed identity stays off (the old key is gone, the new one was not accepted): click Save Config (or Reset identity again) to register a new key.

Every attempt and outcome is in the table conviro_identity_reset_audit: admin user id and username, UTC time, the website / store view codes, the request id, the outcome (started, retried, confirmed, ambiguous, refused, failed_registration, registered), counts and 8-character key id prefixes — never a key, token or customer data; kept 365 days. Conviro's own audit entry (magento.identity.reset) carries the request id, the counts and magento_admin:<admin user id> — never the username.

The manual way (a Conviro backend without Reset identity):

1. Ask Conviro to switch magento_identity_bridge off for your workspace — within a minute no verification is accepted and live ones are revoked. (If you cannot reach Conviro: set Enable signed customer identity = No on every website and Save Config — the store stops signing and refuses order reads at once, and the registration Save Config sends makes Conviro refuse the verifications already made.)
2. Rotate identity key.
3. Wait 5 minutes (the old key's overlap), then ask Conviro to switch the flag back on.
4. Test identity bridge.

The same reset from the Conviro dashboard (owner / admin, a typed confirmation) is built on the backend branch (Phase 5 P5-06 a6ed430a, P5-14 afb631fc; unit-tested, not deployed). It is a different action: it may cover every Magento integration of the workspace. The Magento card's reset never reaches beyond its own store.

After changing Magento's encryption key (bin/magento encryption:key:change): run Test identity bridge; if the step This store signed a synthetic test assertion with its identity key fails, rotate the key. Live sign-out tracking is lost for up to 16 minutes either way (bindings are keyed with the encryption key), then it recovers by itself.

Privacy requests

• Delete a shopper: delete the customer in Magento as usual. The module revokes their sign-in bindings, tells Conviro (which ends their verifications), and deletes their binding rows in the same deletion (Phase 5; before it the rows went within a day). To remove their chats — including sealed order answers and the order they handed to your team — delete the conversations with Conviro's GDPR tools (Privacy › Deletion). Conviro keeps expired verification rows (customer id, no name or e-mail) until the conversation is deleted; the 7-day purge (P5-04 b520da97) and their deletion on customer.deleted (P5-05 368c9808) are built on the backend branch, not deployed (details).
• What Conviro stores about a verified shopper: see the same section — the Magento customer number, store view, times; never their name, e-mail or address from this feature.

What to send Conviro support

• A screenshot of the Customer Experience & Identity card (it holds no customer data and no secret), the result of Test identity bridge, the store view code, and the time (UTC) a shopper failed.
• The diagnostics bundle if support asks for it.
• Never: session cookies, the bootstrap's answer, an assertion, the widget's x-widget-identity header or the signing key.

What Conviro aims for

Planned service levels (1.5.0 Phase 5; targets set 2026-09-28, reviewed after 30 days of production data; nothing is measured in production yet): verification under 1 second and the first order card under 2 seconds for 95 % of shoppers; 99.9 % of order reads answered correctly where Conviro is the cause — failures caused by your store (timeouts, errors, a missing permission) are counted separately and shown to you, not hidden. How each is measured, the alerts behind them and what was measured so far: Performance and SLOs.