Keys and modes

Every key belongs to one store and one mode (test or live). Create and manage them in Studio → Developers → API keys. The full key is shown once; we store only a hash.

Three kinds of key

Kind	Prefix	Where it goes	What it can do
Publishable	pk_test_… / pk_live_…	Your web pages and apps	Show the size guide, open the window, read the shopper’s recommended size. Works only from the origins you register
Secret	sk_test_… / sk_live_…	Your server only	Every server scope of its store
Restricted	rk_test_… / rk_live_…	A partner’s server (returns platform, PLM, BI)	Only the scopes you choose

Never put a secret or restricted key in a page or an app. The web SDK throws secret_key_in_browser and the mobile SDKs throw secret_key_in_app if you try.

Test and live mode

The mode belongs to the key: a request made with a test key is a test request.

	Test	Live
Origins	The origins you add for test mode, plus localhost	Only origins covered by a verified domain
Garments answered	Drafts and published versions (designers can preview before publishing)	Published versions only
Shoppers	Real shopper accounts can sign in; the window shows a “TEST MODE” ribbon	Real shoppers
Billing	Never metered	Fit checks are metered
Limits	1,000 fit checks per day per store	By plan
Analytics, A/B, webhooks	Kept separate from live	Live

The catalog is shared by both modes: you do not keep two catalogs. Test mode answers drafts, live mode answers published versions, so a draft never reaches live shoppers.

Key scopes

A secret key has every scope. A restricted key has only the scopes it was created with; a call outside them answers 403 forbidden. Each operation in the API reference lists its Key scopes.

Scope	Allows
products:read	List and read products, size maps, garments and fit groups
products:write	Create and update products, size maps and fit groups
garments:write	Create and edit garment drafts
garments:publish	Publish a garment version (shoppers are fitted against it)
orders:write	POST /v1/orders
returns:write	POST /v1/returns
fit_checks:read	POST /v1/recommendations (server-side recommendations)
audit:read	GET /v1/audit_events
analytics:read, webhooks:manage	Reserved for server endpoints that are coming soon

Origins

A publishable key works only on the sites you register for it, per store and mode, in Studio → Settings → Stores → Allowed sites.

• https:// origins only, no path. http:// only for localhost, in test mode.
• https://*.brand.com matches subdomains (not the apex brand.com).
• Live origins must be covered by a verified domain. A verified apex domain covers its subdomains.
• Up to 50 origins per mode.
• Apps register an app origin: ios-app://<bundle id> or android-app://<package> (lower case). App origins are accepted in test mode only today; live mode for apps needs app verification, which is coming soon.

Rolling and revoking keys

• Roll a key to replace it without downtime. The new key has the same kind, mode, name and scopes. Choose how long the old key keeps working: now, 1h, 24h or 7d. After that it answers 401.
• Revoke stops a key at once.
• Creating, rolling or revoking a live secret or restricted key asks you to sign in again.
• Up to 20 working keys per store and mode.
• Every key shows when it was last used (updated at most once a minute). Every change is in your audit log.

IP allow-list

Secret and restricted keys can be limited to a list of IP addresses; a call from any other address is refused. The Studio screen for it is coming soon: until then, ask support to set one.

Rate limits

See Rate limits.