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.

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.