Authentication and environments

Every Headless API request uses the Headless key in the X-Antla-SDK-Key header. The merchant copies it as Antla SDK key or Antla Headless key. A key identifies one store. It works when Headless SDK, Headless API, or both are enabled.

Keep these credentials separate

Credential	Purpose	Where it belongs
Antla Headless key	Authenticate Antla Headless API requests	Storefront SDK attribute, app client or your backend
Shopify public Storefront token	Query Shopify product/settings data and use Storefront cart operations	Storefront clients; Antla /context only after Headless SDK is connected
Shopify private Storefront token	Merchant’s server-side Shopify connection	Antla connection setup or an authorized server only
Shopify Admin API credentials	Administrative Shopify access	Authorized server infrastructure; never these examples
Shopify cart ID including its key	Refer to one shopper’s cart	That shopper’s private session; never shared examples or logs

The Antla Headless key is intended for storefront use. It is not a Shopify customer login token and does not prove the identity of an individual shopper. Treat job IDs, photo URLs, cart IDs and visitor IDs as shopper data.

Example environment

SDK script
https://cdn.app-antla.com/antla-sdk/antla-sdk.js

Headless API base
https://app-antla.com/api/headless

Examples use production hosts and YOUR_ANTLA_SDK_KEY. Copy the exact script URL, API base URL, and key shown together in that merchant’s Antla installation if they differ. Connect Headless SDK for the script. Connect Headless API for the API base URL. If both are on, the key is shared.

The SDK’s API origin is built into the script. There is no api-url attribute. Use the script and key from the same installation.

HTTP example

const response = await fetch(
  "https://app-antla.com/api/headless/funnel?funnelIds=1",
  {
    headers: { "X-Antla-SDK-Key": "YOUR_ANTLA_SDK_KEY" },
    credentials: "omit",
  }
);
const body = await response.json();
if (!response.ok) throw new Error(body.message || body.error);

GET /context is a separate check. It also requires Headless SDK. An API-only key still authenticates other routes and returns 403 SDK_NOT_CONFIGURED on /context.

Use Content-Type: application/json for Antla POST requests. Do not substitute Authorization: Bearer or a Shopify token for the SDK-key header.

The API supports cross-origin browser calls with Access-Control-Allow-Origin: *, and allows Content-Type and X-Antla-SDK-Key request headers. Preflight OPTIONS responds with 204. Retry-After is exposed to browser JavaScript. Cookies are not required.

Key refresh and disconnect

A key refresh replaces the active key immediately for the SDK and the API. Reconnection also replaces it when no active key existed. There is no documented grace period with two active keys.

Coordinate deployment updates for web and mobile apps. Mobile releases can remain installed with an old embedded configuration, so design a way to update non-secret environment and key configuration without requiring every user to install a new build.

On 401, verify the environment, the key, and whether SDK or API is still enabled. Repeating the request without fixing the configuration does not restore access.

Merchant and visitor scope

Use one key per merchant connection. The API does not accept a shop field to switch stores. Product IDs, funnel IDs and job IDs must belong to the key’s store.

Polling checks the job ID and store, not the supplied visitor ID. uniqueUserId is used for visitor accounting, not as job-access authentication. Keep job IDs unguessable and unexposed in your application, and add your own user authorization if your backend exposes a job lookup to signed-in users.