# Keys and modes

> Publishable, secret and restricted keys; test and live mode; key scopes, origins, rolling keys and IP allow-lists.

Source: https://docs.tryyoursize.com/get-started/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](https://docs.tryyoursize.com/get-started/going-live.md#verify-your-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](https://docs.tryyoursize.com/api/reference.md) 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](mailto:support@tryyoursize.com) to set one.

## Rate limits

See [Rate limits](https://docs.tryyoursize.com/guides/rate-limits.md).