Authentication

Use this guide when creating API keys, deciding which key belongs in which environment, or debugging 401 and 403 responses.

Key types

Secret keys are server-only. Use them for template, render, product mapping, embed session, and webhook endpoint management.

Restricted keys are server-only keys with limited scopes.

Publishable keys are browser-safe only when paired with allowed origins. Use them for product mapping resolution and guest embed sessions.

Embed-session client secrets are short-lived, session-scoped browser tokens. They authenticate embed fill create/update/complete and live preview calls; they are not team API keys.

Server requests

curl https://api.stackfill.com/v1/templates \
  -H "Authorization: Bearer stackfill_live_sk_REPLACE_ME"

Browser publishable requests

The widget handles this for normal storefront embeds. Direct browser requests should send the publishable key as a header.

curl https://api.stackfill.com/v1/embed/sessions/guest \
  -H "X-StackFill-Publishable-Key: stackfill_live_pk_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"external_product_id":"business-card"}'

Common errors

invalid_api_key means the bearer key is missing, malformed, revoked, or not found.

insufficient_scope means a restricted key does not include the required scope.

origin_not_allowed means the publishable key is not valid for the current browser origin.

See Errors and API reference.

Embed fill preview requests

The live fill preview accepts either the header or query form:

curl "https://api.stackfill.com/v1/embed/fills/FILL_ID/preview?w=880&dpr=2" \
  -H "X-StackFill-Client-Secret: es_REPLACE_ME" \
  --output preview.png

?client_secret=es_… remains available for compatibility, but query URLs can enter browser history, copied URLs, referrer headers, proxy logs, or analytics. New integrations should use the header, fetch the image bytes, and display a local blob URL. Both forms expire with the embed session.