Authentication
Publishable and secret keys, and where each one belongs.
Viewa uses two API-key tiers, in the same pattern as Stripe. A route's key requirement is a minimum tier: a secret key satisfies a publishable-key requirement, but a publishable key cannot satisfy a secret-key requirement.
| Key | Prefix | Where it lives | What it can do |
|---|---|---|---|
| Publishable key | pk_ | The customer's browser | Access browser-safe routes when the request's Origin is on the key's allowlist |
| Secret key | sk_ | Your server only | Satisfy any API-key tier, including publishable- and secret-key routes |
Both are sent as a bearer token; substitute the key appropriate to the caller:
Authorization: Bearer <api-key>Publishable keys are domain-locked
A publishable key is the browser-safe minimum tier. It is safe to ship in your
storefront's JavaScript because it is not a secret and can access only the
browser-safe subset of routes. Browser requests are accepted only when their
Origin is on the key's allowlist. If you see authentication failures from the
browser, check that the page's origin is on the allowlist.
Manage the allowlist from your server with the matching secret key:
list, add and
remove origins at /api/v1/origins. Each key pair
has its own list, and a publishable key can never change it.
Secret keys
Your secret key satisfies either API-key tier (pk or sk). Use it only from your
server: it does not require an Origin header, and any Origin forwarded by a proxy
is ignored for secret-key authentication. Never put an sk_ key in browser or other
client-side code. Some routes are secret-key only: GET /api/v1/usage — the
per-key usage report — SKU
alias management, the origin allowlist,
and DELETE /api/v1/visitors/{id}, which deletes one shopper's
data on request. Treat it like a password: store it in server-side environment
variables, not source control.
A secret key is not a master bypass. It satisfies the API-key tier only. Visitor tokens, instance scoping, quotas and metering, and any route-specific authorization requirements still apply.
If a secret key is exposed, contact the Viewa team to rotate it.
Visitor tokens
An API key identifies your shop, not your customer. The pipeline endpoints — images, areas, renders, and history — also understand a visitor token, sent in its own header:
Authorization: Bearer pk_...
X-Viewa-Visitor-Token: vis_...The token is issued by the first POST /api/v1/images and is what keeps one
shopper from reading another's uploads and renders. A secret key does not
substitute for it.
Whether the token is mandatory on those endpoints is a per-instance setting,
off by default; the history endpoint always requires it. Send it either way — a
token you send always scopes the call. See Visitor tokens &
privacy for issuance, refresh, expiry,
the instance policy, and the two 403 codes to handle.
Getting keys
Keys are issued per instance by the Viewa team during onboarding — contact your Viewa representative. Self-service key management is planned.