Etsy Open API Compliance

- Personal mode (production default): AtlasCore requests only `shops_r listings_r profile_r`. Receipt, inventory-write, listing-write, and messaging scopes are not requested until `ETSY_COMMERCIAL_MODE=true` and Etsy-approved `COMMERCIAL_ETSY_SCOPES` are configured.

• API calls are made on behalf of the authenticated shop owner who completed the OAuth consent flow.
• In personal mode, tokens are used to provide shop identity and read-only listing snapshots. Listing writes (`listings_w`) and receipt access (`transactions_r` / `transactions_w`) stay blocked until commercial approval.
• Cached listing snapshots are refreshed to stay inside Etsy's 6-hour display window (`CACHE_TTL_LISTINGS_SECONDS`). Refresh may be seller-initiated (`POST /sync/listings/`) or a background listing-only scheduled sync. That scheduled job does not pull receipts or write listings.
• Commercial mode additionally enables order/receipt sync, fulfillment tracking, and listing writes the seller initiates after Etsy scope approval.

- Dedicated account tables — Etsy OAuth tokens, listings, and orders persist on Etsy account rows keyed by the signed-in AtlasCore user.

• Encrypted credentials — Access and refresh tokens are stored only as `enc:v1:` ciphertext on the linked `EtsyAccount`. App secrets and webhook signing keys are deployment environment variables, not merchant-row fields.
• Route-level isolation — Etsy API handlers resolve the caller's linked `EtsyAccount` only.
• Logging hygiene — API error sanitization redacts token-like strings and buyer PII before logs are written.

- Default boundary: Etsy shops are user-scoped B2C. Sync jobs, webhook handlers, and dashboard queries resolve the authenticated user's own `EtsyAccount`.

• Optional workspace overlay: When an organization binds a shop, `tenant_id` / `X-Tenant` further scopes that user's Etsy rows. `tenant_id` is nullable and is not required for personal shops.
• Administrative and operator tools apply role-based access controls (RBAC). Operator webhook event inspection requires a valid registered Etsy shop identifier (`shop_id` that maps to a connected shop) and authorized administrative context. Unknown shop identifiers are rejected. When a shop has multiple workspace bindings, `tenant_id` is also required.

- AtlasCore caches only the Etsy fields needed for in-product features.

• Disconnect in AtlasCore destroys locally stored Etsy OAuth ciphertext and cached shop data. Etsy's Open API does not expose a public token-revoke endpoint, so AtlasCore cannot remotely invalidate the grant at Etsy.
• Remote revocation: In the Etsy account (Apps / Developer Portal permissions), revoke AtlasCore to invalidate tokens at the source. See also Disconnect Marketplace.