Mai Authentication

generated: '2026-08-12'
method: derived
source: >-
  npm @mai-co/pixel@1.0.5 — dist/mai-pixel.es.js (transport + config modules),
  dist/types.d.ts, dist/config.d.ts, and the published README integration guide
docs: https://www.npmjs.com/package/@mai-co/pixel
summary: >-
  MAI's one publicly reachable API — the Pixel Event Collection endpoint at
  POST https://pixel.mai.co/api/collect — is UNAUTHENTICATED. There is no API
  key, no bearer token, no signature and no securityScheme of any kind. The
  request carries no credential; the tenant is named in the body as a plaintext
  Shopify store domain, and the visitor is identified by a first-party cookie
  the SDK itself mints. Every other MAI surface (the Shopify embedded app, the
  web application) sits behind Shopify OAuth or an application login that is not
  publicly documented.
security_scheme_count: 0
schemes: []
model:
  authenticated: false
  credential: none
  transport_security: TLS 1.3 (HTTPS enforced)
  tenant_identification:
    field: shop.myshopifyDomain
    location: request body
    source: MaiConfig.storeDomain, supplied by the embedding site
    secret: false
    note: >-
      The store domain is configuration, not a credential. It is visible in page
      source on every storefront that installs the pixel, so it identifies the
      tenant but does not authenticate it.
  subject_identification:
    field: client_id
    location: request body
    source: '_mai_cid cookie — UUID v4 minted client-side, 2-year max-age'
    note: >-
      Anonymous pseudonymous identifier. Upgraded to a named identity only when
      the merchant calls MaiPixel('setCustomer', ...) with an email or phone.
  consent_gate:
    mechanism: MaiPixel('consent', ...)
    aligned_with: Shopify CustomerPrivacy API
    fields:
      - analytics_processing_allowed
      - marketing_allowed
      - preferences_processing_allowed
      - sale_of_data_allowed
    default: >-
      Tracking is ALLOWED by default. If consent() is never called the SDK sends
      events. Setting analytics_processing_allowed to false halts all sends.
    note: >-
      This is the only client-side gate on the endpoint, and it is enforced in
      the browser by the SDK — not by the server.
observations:
  - >-
    Because the endpoint is unauthenticated and accepts a caller-supplied store
    domain, nothing in the published contract prevents a third party from
    posting events attributed to another merchant's store. MAI may apply
    server-side validation that is not visible from the client bundle; none is
    documented.
  - >-
    The SDK sends the body with Content-Type text/plain (both the
    navigator.sendBeacon Blob and the XHR fallback), which keeps the request a
    CORS simple request and avoids a preflight. A consequence is that no
    Authorization header could be added without changing that property.
  - >-
    MaiConfig exposes an apiEndpoint override documented as "for debug/staging
    only", so the collection host is configurable by the embedding site.
gaps:
  - No published authentication documentation for any MAI API.
  - No OAuth 2.0 / OpenID Connect metadata on any host (all /.well-known/ probes miss).
  - No API key issuance, rotation, or revocation story is published.