Widget origins and access

The public /api/widget/* endpoints identify the merchant using merchantId and check the storefront origin against the widget configuration. The browser supplies Origin for cross-origin requests. These endpoints do not use merchant Bearer API-key authentication.

The merchant ID and script slug are public storefront identifiers. Keep database, payment-provider, and inference-provider credentials on the server.

Use an active widget configuration and explicitly list each intended storefront origin, for example https://store.example.com. Matching compares scheme, hostname, and port; paths are not part of an origin. Add staging and alternate hosts separately. An empty allowed-origin list denies access in production.

If the dashboard does not expose the setting, contact Closku with your merchant ID and origins. Production requests can return HTTP 403 with config_not_found, widget_inactive, or origin_not_allowed. Do not rely on development allowances for a live store.

Origin validation controls storefront access. It does not make a merchant identifier secret or establish a general server-to-server authentication contract.

Create an anonymous shopper session through POST /api/widget/session. Use its sessionId with the same merchant ID and submit before the returned expiresAt. The server checks that the session exists, belongs to that merchant, and has not expired before creating a job. Create a fresh session after expiry; do not reuse a session from another merchant.

Submit the shopper photo as a supported base64 image data URL. HTTP(S) shopper-photo URLs are rejected. The service stores the uploaded photo and gives processing a temporary signed access URL; the database keeps a storage path rather than a permanent public photo URL.

Job status lookup is also scoped to the supplied merchant ID. Keep the returned job ID together with its merchant ID for polling.

The dashboard uses a signed-in Closku session and merchant membership. Checkout and customer-portal actions require the merchant owner role. Perform them through the dashboard; storefront code must not impersonate the account owner.

For a custom server integration or separately provisioned contract, ask Closku for current access requirements. This reference covers the application's storefront routes.