Authentication
How API requests are authenticated — session cookies, API keys, and terminal keys.
Saleporia uses several authentication mechanisms depending on the client and operation. The Store API uses shop API keys; admin routes use session cookies; POS terminals use terminal keys.
Shop API keys (Store API)
Every shop has two API keys created at signup: a publishable key (read-only, safe for client-side) and a secret key (read/write, server-side only). Send your key in the Authorization header as a Bearer token.
GET /v1/store/products HTTP/1.1
Host: api.saleporia.com
Authorization: Bearer sp_live_xxxxxxxxxxxx
x-shop-id: your-shop-slugAuth levels
| Field | Type | Description |
|---|---|---|
| publishable | key | Read-only access. Safe to expose in client-side apps and storefronts. Prefix sp_pub_. |
| secret | key | Full read/write access. Never expose client-side. Prefix sp_live_. Required for all POST/PATCH/DELETE operations. |
Protect your secret key
Session auth (admin)
Admin routes are authenticated with a JWT session cookie issued at login (OTP or Google). The cookie is httpOnly and lasts 30 days (email OTP) or 7 days (Google). Admin requests also require an x-shop-id header to scope the active shop.
Customer auth (storefront)
Shopper sessions are JWT cookies scoped to a shop, issued via the storefront-customer OTP flow. They're used for account pages, order history, and loyalty.
Terminal auth (POS)
POS terminals authenticate with an auto-generated terminal access key (separate from shop API keys). Register a terminal in shop settings, then use its key for POS product lookups.
Active shop context
Most authenticated requests require an x-shop-id header identifying the active shop. This lets a single user own and staff multiple shops. The Store API infers the shop from the API key, so x-shop-id is optional there.
Related