API

Studio Sessions

Create, verify, and configure secure Studio sessions. Embed a real-time mockup editor in your storefront via iframe, popup, or full page.

POST/api/v1/studio/create-session

x-api-key / Shopify HMAC

POST/api/v1/studio/verify-session

No auth required

GET/api/v1/studio/config

x-api-key / Studio session

PUT/api/v1/studio/config

x-api-key only

API Key Never Exposed

Session tokens are opaque (sess_ + 43 random characters). Your API key is stored server-side and never included in the token or any client response. Sessions auto-extend their expiry on use. Safe for use in public-facing iframes.

Authentication

Studio endpoints use three authentication schemes depending on the endpoint and caller:

Scheme	Header / Mechanism	Used By
API Key	`x-api-key: sm_your_api_key`	create-session, GET config, PUT config (server-to-server)
Studio Session	`Authorization: Studio sess_xxx`	GET config (from the Studio iframe at runtime)
Shopify HMAC	Shopify App Proxy signature (query params)	create-session (Shopify storefronts via App Proxy)

Studio Session Auth

The Authorization: Studio sess_xxx scheme is used by the Studio editor itself when making API calls during an active session. Your API key is stored server-side and never included in the token or any client response. This header is accepted by GET /config and the render endpoint.

How It Works

Your server creates a session

Call POST /studio/create-session with your API key (server-to-server). The API verifies ownership of the mockup and generates an opaque token.

Pass the token to the client

Send only the sess_xxx token to your frontend. The API key stays on your server.

Studio verifies and loads config

Studio calls POST /studio/verify-session to validate the token and receive session info + customization config in a single round-trip.

Open Studio with the session

Load studio.sudomock.com/editor?session=sess_xxx in an iframe, popup, or redirect based on displayMode.

Session auto-extends

Every API call made within the session resets the 15-minute TTL. Active sessions never expire while the user is interacting.

POST /create-session

Generates an opaque session token for the Studio editor. Requires x-api-key header (WooCommerce, custom integrations) or Shopify App Proxy HMAC signature. The API key never leaves the server.

Headers

x-api-keystring

Your SudoMock API key starting with sm_. Required unless using Shopify HMAC authentication.

Content-TypestringRequired

Must be application/json

Request Body

mockup_uuidstringRequired

UUID of the mockup to open in Studio. Must belong to the authenticated account.

product_idstring

Product identifier from your platform (e.g., Shopify Product GID, WooCommerce product ID). Stored in the session for your reference.

shopstring

Store domain (e.g., 'my-store.myshopify.com'). Required for Shopify HMAC flow. For x-api-key auth, optional and stored as-is in the session. Max 255 characters.

Request Body Example

1{
2  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
3  "product_id": "gid://shopify/Product/123456",
4  "shop": "my-store.myshopify.com"
5}

Response

200OK

Response 200 OK

1{
2  "success": true,
3  "session": "sess_3_TU1FyqABbmj28yg_-YqENaK-CnvsxBuovgmiT_RHc",
4  "expires_in": 900,
5  "displayMode": "iframe"
6}

successbooleanRequired

Always true on success. Errors return HTTP exceptions.

sessionstringRequired

Opaque session token. Format: sess_ followed by 43 URL-safe random characters (e.g., sess_3_TU1FyqABbmj28yg_-YqENaK-CnvsxBuovgmiT_RHc). Pass this to the Studio URL. Never contains your API key.

expires_inintegerRequired

Session lifetime in seconds (900 = 15 minutes). Auto-extends on every Studio interaction, so active sessions stay alive.

displayModestringRequired

How Studio should be displayed. One of: "iframe", "popup", or "page". Configured per API key in your Studio settings.

Display Modes

Mode	Behavior	Best For
`iframe`	Embed in an iframe on your page	Product pages, inline customization
`popup`	Open in a new browser window	Quick customization without leaving the page
`page`	Full-page redirect	Mobile-first experiences, dedicated editor

Error Responses

400Bad Request

json

1{
2  "detail": "Missing shop parameter"
3}

Shopify HMAC flow only: the shop query parameter is missing, or the timestamp parameter is not a valid integer.

401Unauthorized

json

1{
2  "detail": "Invalid or inactive API key"
3}

The API key is missing, invalid, or has been deactivated. For Shopify, this means the HMAC signature verification failed or the request has expired (older than 5 minutes).

403Forbidden

json

1{
2  "detail": "Mockup not found or does not belong to this account"
3}

The mockup_uuid does not exist or belongs to a different account.

404Not Found

json

1{
2  "detail": "Store not connected"
3}

Shopify HMAC flow only: the shop domain is not linked to any SudoMock account.

Code Examples

Create Studio Session

bash

1curl -X POST "https://api.sudomock.com/api/v1/studio/create-session" \
2  -H "Content-Type: application/json" \
3  -H "x-api-key: sm_your_api_key" \
4  -d '{
5    "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
6    "product_id": "product-123"
7  }'

POST /verify-session

Validates a session token and returns session info together with the merchant's Studio customization config in a single response. This saves the Studio editor a separate round-trip to GET /config. Sessions auto-extend their expiry on successful verification. Your API key is stored server-side and never included in the token or any client response.

No Authentication Required

This endpoint does not require an API key or session header. The session token in the request body is the proof of validity. Invalid or expired tokens return {"valid": false} instead of an HTTP error.

Headers

Content-TypestringRequired

Must be application/json

Request Body

sessionstringRequired

The opaque session token to verify (e.g., sess_3_TU1FyqABbmj28yg_-YqENaK-CnvsxBuovgmiT_RHc). Must start with sess_ prefix.

Request Body

1{
2  "session": "sess_3_TU1FyqABbmj28yg_-YqENaK-CnvsxBuovgmiT_RHc"
3}

Response

200OK

Always returns 200, even for invalid tokens. Check the valid field to determine session status.

Response - Valid Session

1{
2  "valid": true,
3  "shop": "my-store.myshopify.com",
4  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
5  "product_id": "gid://shopify/Product/123456",
6  "config_version": 3,
7  "expires_at": "2026-03-22T14:30:00+00:00",
8  "studio_config": {
9    "displayMode": "iframe",
10    "brandColor": "#FF5733",
11    "logoUrl": "https://my-store.com/logo.png"
12  }
13}

Response - Invalid / Expired Session

1{
2  "valid": false,
3  "shop": null,
4  "mockup_uuid": null,
5  "product_id": null,
6  "config_version": null,
7  "expires_at": null,
8  "studio_config": null
9}

Response Fields

validbooleanRequired

Whether the session token is valid and active. If false, all other fields are null.

shopstring | null

Store domain associated with the session (e.g., 'my-store.myshopify.com'). May be empty string for non-Shopify integrations.

mockup_uuidstring | null

UUID of the mockup locked to this session.

product_idstring | null

Product ID from the platform, if provided when the session was created.

config_versioninteger | null

Studio config version number. Use this for client-side cache busting when the merchant updates their Studio configuration.

expires_atstring | null

ISO 8601 timestamp when the session expires. This is recalculated on every verify call since the TTL auto-extends.

studio_configobject | null

Merged Studio customization settings for the merchant (branding, display preferences, feature flags). Same data returned by GET /config.

GET /config

Returns the merchant's Studio customization settings. Accepts either x-api-key header or Authorization: Studio sess_xxx header. Since verify-session already includes config in its response, this endpoint is mainly useful for mid-session config refresh without re-verifying the full session.

Headers

Provide one of the following:

x-api-keystring

Your SudoMock API key starting with sm_.

Authorizationstring

Studio session token in the format: Studio sess_xxx. Used by the Studio editor during an active session.

Response

200OK

Response 200 OK

1{
2  "success": true,
3  "config": {
4    "displayMode": "iframe",
5    "brandColor": "#FF5733",
6    "logoUrl": "https://my-store.com/logo.png"
7  },
8  "config_version": 3
9}

Response Fields

successbooleanRequired

Always true on success.

configobjectRequired

The merchant's Studio customization settings (branding, display preferences, feature flags). Empty object if no config has been set.

config_versionintegerRequired

Config version number, incremented on every PUT /config update. Starts at 0.

Error Responses

401Unauthorized

json

1{
2  "detail": "API key or session token required"
3}

No x-api-key header and no Authorization: Studio header provided. Or the Studio session token is invalid/expired.

404Not Found

json

1{
2  "detail": "API key not found"
3}

The API key resolved from the header (or session) is not active or does not exist.

Example

GET /config

1# Using API key
2curl "https://api.sudomock.com/api/v1/studio/config" \
3  -H "x-api-key: sm_your_api_key"
4
5# Using Studio session token (from within the Studio iframe)
6curl "https://api.sudomock.com/api/v1/studio/config" \
7  -H "Authorization: Studio sess_3_TU1FyqABbmj28yg_-YqENaK-CnvsxBuovgmiT_RHc"

PUT /config

Updates the merchant's Studio customization settings. The provided config is shallow-merged with the existing config (new keys are added, existing keys are overwritten). The config_version is incremented automatically. Requires x-api-key header (Studio session tokens are not accepted for config writes).

API Key Only

This endpoint requires the x-api-key header. Studio session tokens (Authorization: Studio) are not accepted for config updates. This prevents end-users from modifying merchant settings through the Studio iframe.

Headers

x-api-keystringRequired

Your SudoMock API key starting with sm_.

Content-TypestringRequired

Must be application/json

Request Body

configobjectRequired

Key-value pairs to merge into the existing Studio config. New keys are added, existing keys are overwritten. Keys not included in this object are preserved.

Request Body

1{
2  "config": {
3    "brandColor": "#3366FF",
4    "logoUrl": "https://my-store.com/new-logo.png",
5    "hideWatermark": true
6  }
7}

Response

200OK

Returns the full merged config (not just the keys you sent) and the new version number.

Response 200 OK

1{
2  "success": true,
3  "config": {
4    "displayMode": "iframe",
5    "brandColor": "#3366FF",
6    "logoUrl": "https://my-store.com/new-logo.png",
7    "hideWatermark": true
8  },
9  "config_version": 4
10}

Response Fields

successbooleanRequired

Always true on success.

configobjectRequired

The full merged Studio config after applying your changes.

config_versionintegerRequired

New config version number (previous version + 1). Active sessions can detect config changes by comparing this against their cached version.

Error Responses

401Unauthorized

json

1{
2  "detail": "x-api-key header required"
3}

No x-api-key header provided. Studio session tokens are not accepted for this endpoint.

404Not Found

json

1{
2  "detail": "API key not found"
3}

The API key is not active or does not exist.

Example

PUT /config

1curl -X PUT "https://api.sudomock.com/api/v1/studio/config" \
2  -H "Content-Type: application/json" \
3  -H "x-api-key: sm_your_api_key" \
4  -d '{
5    "config": {
6      "brandColor": "#3366FF",
7      "logoUrl": "https://my-store.com/new-logo.png",
8      "hideWatermark": true
9    }
10  }'

Security Model

Studio sessions are designed with a zero-trust approach to API key protection:

API key never leaves the server

Stored server-side and never included in the token or any client response

Opaque tokens are not decodable

Session tokens are cryptographically random strings (secrets.token_urlsafe), not JWTs. No sensitive data is embedded.

Mockup ownership enforced

Each session is locked to a specific mockup at creation. The session cannot be used to access other mockups.

15-minute TTL with auto-extend

Inactive sessions expire automatically. Active sessions extend on every verify-session call and every API call using the session token.

Shopify HMAC replay protection

Shopify App Proxy requests are verified via HMAC-SHA256 signature and rejected if older than 5 minutes.

Config writes restricted to API key

PUT /config requires x-api-key header. Studio session tokens cannot modify merchant settings, preventing iframe-based config tampering.

Iframe Integration Example

A complete example showing how to embed Studio in your product page:

Complete Iframe Integration

1<!-- Your product page HTML -->
2<div id="studio-container" style="width: 100%; height: 700px; display: none;">
3  <iframe
4    id="studio-frame"
5    style="width: 100%; height: 100%; border: none; border-radius: 12px;"
6    allow="clipboard-write"
7  ></iframe>
8</div>
9
10<button id="customize-btn" onclick="openStudio()">Customize This Product</button>
11
12<script>
13async function openStudio() {
14  // 1. Request session from YOUR backend (not directly from the browser)
15  const res = await fetch("/api/studio-session", {
16    method: "POST",
17    headers: { "Content-Type": "application/json" },
18    body: JSON.stringify({
19      mockup_uuid: "c315f78f-d2c7-4541-b240-a9372842de94",
20      product_id: "product-123"
21    })
22  });
23  const { session, displayMode } = await res.json();
24
25  // 2. Open Studio based on displayMode
26  const studioUrl = `https://studio.sudomock.com/editor?session=${session}`;
27
28  if (displayMode === "iframe") {
29    document.getElementById("studio-frame").src = studioUrl;
30    document.getElementById("studio-container").style.display = "block";
31    document.getElementById("customize-btn").style.display = "none";
32  } else if (displayMode === "popup") {
33    window.open(studioUrl, "SudoMock Studio", "width=1200,height=800");
34  } else {
35    window.location.href = studioUrl;
36  }
37}
38</script>

Server-Side Session Creation

Always create sessions from your backend server. Never call /create-session directly from the browser, as this would expose your API key in the network request.

Plans Error Handling