Authentication

Store keys, customer bearer tokens, outlet selection, and the internal service token.

This page is the API-level reference for auth headers. For the conceptual overview (and how the SDK handles all of this), see Concepts → Authentication.

X-Store-Key (required on /v1)

Identify the store with your publishable key:

GET /v1/products HTTP/1.1
Host: api.your-storekit.com
X-Store-Key: sk_live_xxx

The key is hashed and looked up server-side; it carries scopes (e.g. products:read) that gate what it can do, and an optional per-key rate limit. Keep it on your server — never ship it to the browser.

Authorization: Bearer (customer)

Customer-scoped endpoints additionally need a session token obtained from POST /v1/auth/otp/verify:

GET /v1/customer/orders HTTP/1.1
X-Store-Key: sk_live_xxx
Authorization: Bearer <session-token>

Sessions last 7 days.
The bearer header is optional on endpoints that support both guest and customer use (e.g. reading a guest cart). Endpoints that strictly require a customer return 401 UNAUTHORIZED without it.

Obtaining a token

POST /v1/auth/otp/request with { "phone": "+91…" } → sends an OTP (logged to the API console in dev).

POST /v1/auth/otp/verify with { "phone": "+91…", "otp": "123456", "guestCartId"?: "…" } → returns { token, customer, expiresAt } and optionally claims a guest cart.

Send Authorization: Bearer <token> on subsequent customer requests.

POST /v1/auth/logout (with the bearer header) invalidates the token.

OTP limits: expire after 5 minutes, 3 verification attempts, 5 requests per phone per hour.

X-Outlet-Id (optional)

For multi-outlet stores, scope a request to a specific outlet:

X-Outlet-Id: out_123

Omit it to use the store's default outlet. Every authenticated request resolves an outlet either way.

X-Internal-Storefront-Token (advanced)

For trusted server-to-server calls you may send an internal HMAC token instead of X-Store-Key. It encodes { storeId, exp }, is signed with a shared secret, and is granted full scope. Most integrations never need this — use the store key.

Quick reference: which endpoints need what

Endpoints	X-Store-Key	Bearer
products, categories, search, store, menu	✅	optional
`auth/otp/request`, `auth/otp/verify`	✅	—
cart (create/get/update by id)	✅	optional (guest vs customer)
cart `me`, delete, claim	✅	✅
checkout, customer, coupons, downloads, payment	✅	✅
webhooks, payment callback	—	provider-specific