Authentication

Every request to the TryOn API is authenticated with an API key.

Header format

Send the key as a bearer token on every request:

Header

Authorization: Bearer tryon_sk_your_key

Request

curl https://api.integration.tryonvirtual.com/v1/products \
  -H "Authorization: Bearer tryon_sk_your_key"

Requests without a valid key get a 401 with the unauthorized error code:

Response — 401

{"error": {"code": "unauthorized", "message": "Invalid or missing API key"}}

Creating a key

Keys are created and revoked in the merchant panel, under Settings → API Keys — there is no API endpoint for key management, this is deliberately admin-only and UI-only. Only admin users on the shop can create or revoke keys.

The full key (tryon_sk_...) is shown once, at creation time. After that, the panel only ever shows a truncated reference — if you lose the key, revoke it and create a new one. There is no way to retrieve a lost key.

Limits

A shop can have at most 10 active keys at a time. If you’re at the limit and need a new one, revoke a key you no longer use first.

Rotating a key

Because a key is only visible once, rotate before you run out rather than after a key stops working:

1. Create a new key in the panel.
2. Update your integration (env var, secret store, wherever it’s configured) to use the new key.
3. Confirm the new key works — a 200 from any authenticated endpoint (e.g. GET /v1/usage) with the new key is enough. /v1/usage reports monthly try-on quota — opens, swaps, product counts — not API call volume, so don’t rely on it to see your integration’s traffic; check your own logs for that.
4. Revoke the old key in the panel.

Keep both keys active during the switch — there’s no outage window, and you can revoke the old one whenever you’re confident the new one is live.

Never expose keys client-side

The API key is a server-side secret. Never put it in storefront JavaScript, a mobile app bundle, or any code that ships to a browser — treat it like a database password.

This isn’t a tradeoff you need to make: the storefront integration never needs a key at all. The bootstrap script that opens the try-on experience on a product page is loaded as a public, unauthenticated URL — all authenticated calls (creating products, adding images, enabling try-on) happen from your backend or build pipeline, not the browser.

Next

Product lifecycle — the three steps that make a product try-on-ready.