Authentication

Publix uses a tiered access model based on a listing's visibility field.

Access tiers

`visibility`	Auth required	Behavior
`"public"`	None	Any anonymous client can read the listing
`"private"`	Embed key	Request must include a valid `X-Publix-Embed-Key`
`"disabled"`	—	Returns `listing: null` regardless of credentials

Embed keys

Embed keys are long-lived secrets with the prefix mbpub_. Listing owners create and manage them inside MyBusiness. A key is tied to a single listing.

The secret is shown only once when issued. Store it immediately in an environment variable or secrets manager.

Passing an embed key

Both forms are accepted and equivalent:

X-Publix-Embed-Key: mbpub_your_key_here

Authorization: Bearer mbpub_your_key_here

Example — custom header

curl -X POST "https://publix-api.mateality.com/graphql" \
  -H "content-type: application/json" \
  -H "x-publix-embed-key: mbpub_your_key_here" \
  -d '{
    "query": "query Listing($slug: String!) { listing(slug: $slug) { slug location { displayName } } }",
    "variables": { "slug": "private-listing" }
  }'

Example — bearer token

curl -X POST "https://publix-api.mateality.com/graphql" \
  -H "content-type: application/json" \
  -H "authorization: Bearer mbpub_your_key_here" \
  -d '{
    "query": "query Listing($slug: String!) { listing(slug: $slug) { slug location { displayName } } }",
    "variables": { "slug": "private-listing" }
  }'

Example — TypeScript server-side

const response = await fetch("https://publix-api.mateality.com/graphql", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-publix-embed-key": process.env.PUBLIX_EMBED_KEY!,
  },
  body: JSON.stringify({ query, variables }),
});

When a listing owner configures allowed origins for their listing, Publix validates the browser Origin header on embed-key requests. If your application is browser-based and the listing has an allowlist, your origin must appear on it.

Origin validation only applies to browser requests. Server-to-server requests are not affected.

Key lifecycle

Action	Where
Issue a key	MyBusiness → listing → Embed keys → New key
Set expiry	Optional expiry date on issue
Revoke a key	MyBusiness → listing → Embed keys → Revoke

Revoking a key takes effect immediately. The listing slug does not change.

CORS

Publix sets open CORS headers on all responses:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Headers: authorization,content-type,x-publix-embed-key

Public listings can be read directly from the browser. For private listings, either proxy through your own server (recommended) or ensure your origin is on the listing's allowlist.

Security guidelines

Do not embed keys in browser code. If your frontend needs to render a private listing, proxy the request through your own server and keep the key in a server-side environment variable.

Do not put keys in URLs. Query parameters are logged by servers, CDNs, and browser history. Use headers.

Do not commit keys to source control. Use environment variables or a secrets manager.

Rotate keys that may be compromised. Revoke the old key and issue a new one from MyBusiness — the listing slug remains the same.