Partner Embed (SSO) integration guide

1. Your backend builds a JSON payload for the current user.
2. Your backend signs the raw JSON string with HMAC-SHA256 + client_secret.
3. Your frontend loads the embed URL with the base64 payload and lowercase hex signature.
4. We verify, create a 12-hour session, and render the Workspace with your logo + accent colour.

Sign server-side only. Your client_secret must never reach a browser.

Both values are issued by Music Video Marketplace during onboarding — there is no public signup and no self-serve credential rotation. Email info@musicvideomarketplace.com to request credentials, to have a secret rotated immediately if it leaks, or to change your embed_mode or stored branding. Your partner record also carries your account status (only active partners can open sessions), partner_type, a monthly per-user download limit, and any partner-wide auto-discount.

1. Serialise the payload once into a JSON string. Keep that exact string.
2. Sign the raw JSON string (not the base64 form) with HMAC-SHA256 and your client_secret.
3. Hex-encode the digest, lowercase.
4. Base64-encode the same raw JSON string for the URL, then URL-encode it.

Worked example (Node)

const crypto = require('crypto');

const CLIENT_ID = 'pk_partner_demo_0000000000000000';
const CLIENT_SECRET = process.env.MVM_CLIENT_SECRET;   // server-side only

// 1. one canonical JSON string — sign and send exactly this
const payloadString = JSON.stringify({
  partner_external_user_id: 'your-user-123',
  email: 'jane@example.com',
  display_name: 'Jane Doe',
  timestamp: new Date().toISOString(),
});

// 2. lowercase hex HMAC of the RAW string
const sig = crypto.createHmac('sha256', CLIENT_SECRET)
  .update(payloadString)
  .digest('hex');

// 3. base64 of the SAME raw string, URL-encoded
const b64 = Buffer.from(payloadString, 'utf8').toString('base64');

const embedUrl =
  `https://musicvideomarketplace.com/partner/embed/${CLIENT_ID}` +
  `?payload=${encodeURIComponent(b64)}&sig=${sig}`;

Same thing in Python

import base64, hmac, hashlib, json, urllib.parse
from datetime import datetime, timezone

payload_string = json.dumps({
    "partner_external_user_id": "your-user-123",
    "email": "jane@example.com",
    "display_name": "Jane Doe",
    "timestamp": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
}, separators=(",", ":"))

sig = hmac.new(CLIENT_SECRET.encode(), payload_string.encode(), hashlib.sha256).hexdigest()
b64 = base64.b64encode(payload_string.encode()).decode()
embed_url = f"https://musicvideomarketplace.com/partner/embed/{CLIENT_ID}?payload={urllib.parse.quote(b64)}&sig={sig}"

Byte-for-byte matters. Re-serialising the object on the way out (different key order, different spacing, a pretty-printer, a trailing newline) changes the bytes and the signature no longer matches. Compare case-insensitively on our side is handled — we lowercase your signature before comparing — but everything else must match exactly.

{
  "partner_external_user_id": "your-user-123",
  "email": "user@example.com",
  "display_name": "Jane Doe",
  "timestamp": "2026-09-02T13:45:00.000Z",
  "logo_url": "https://cdn.yourbrand.example/logo.svg",
  "accent_color": "#1D4ED8"
}

Unknown extra keys are ignored (they are still covered by the signature). Entitlement cannot be asserted in the payload — see “Entitlement model” below.

https://musicvideomarketplace.com/partner/embed/{CLIENT_ID}?payload={BASE64_JSON}&sig={HEX_HMAC}

payload is base64 of the signed JSON string, URL-encoded. sig is the lowercase hex HMAC of the raw JSON string. Both are required; without them the embed renders a “missing session” state and no session is created. If payload is not valid base64 we fall back to treating it as the raw JSON string, so sending raw JSON also works — base64 is preferred because it survives URL encoding cleanly.

Recommended host page pattern

<iframe
  id="mvm-embed"
  title="Music Video Marketplace Workspace"
  style="width:100%;height:100%;min-height:720px;border:0;border-radius:12px;background:#0F0F10"
  allow="autoplay; fullscreen; clipboard-write"
></iframe>
<script>
  // your endpoint, your auth — it mints a fresh signed URL per load
  fetch('/api/mvm-embed-url')
    .then((r) => r.json())
    .then(({ embedUrl }) => { document.getElementById('mvm-embed').src = embedUrl; });
</script>

Sizing & responsiveness

• The embed is a full-application surface, not a widget: it lays itself out to 100dvh of the iframe viewport and scrolls internally. Give the iframe a real height — a flex/grid cell that fills your page, or an explicit height. Do not rely on content-based auto-height; the iframe will collapse.
• Minimum usable height is about 720px for the Workspace editor (timeline + preview + panels). Below roughly 620px height or 480px width the embed switches to a compact layout, and below 420px height / 320px width to a “tiny” layout; the editor timeline is cramped at those sizes.
• We never resize your iframe and never post height messages to your page — sizing is entirely yours. Full-screen-style surfaces such as export history are rendered as modals inside the iframe, so they need no host cooperation and no extra height.
• allow="autoplay; fullscreen; clipboard-write" is required for video playback, full-screen preview and copy-to-clipboard actions to work.
• Do not sandbox the frame without allow-scripts allow-same-origin allow-popups allow-forms; the Workspace needs script execution, its own origin storage, and popups for checkout.

Your partner record carries an embed_mode column with two values. It is returned as embed_mode in the verification response and decides what the embed renders after sign-in.

Configuration is admin-side, not self-serve. There is no partner UI and no payload field for it — partners.embed_mode is set by Music Video Marketplace on request, and it cannot be overridden per session or per user from your side. Ask us to switch it; the change takes effect on the next session.

logo_url and accent_color are part of the signed payload, so they are covered by the same HMAC signature as the identity fields and cannot be injected from a browser without your client_secret. There is no separate branding signature and no separate branding endpoint.

Resolution order, evaluated per field, per session:

1. Signed payload — logo_url / accent_color, when present and valid.
2. Stored config — partners.branding_config.logoUrl / .primary, set by your partner manager.
3. Default — no partner branding (null).

Validation

• logo_url must parse as a URL with an http: or https: protocol. Use https.
• accent_color must match /^#[0-9a-fA-F]{6}$/. Shorthand (#abc), named colours and rgb() are rejected. Accepted values are normalised to uppercase.
• Invalid values are ignored, never fatal: the session still boots and falls through to the stored value, then to default. A malformed colour can never lock your users out.

The verification response echoes what was actually used in branding_source — the fastest way to confirm your fields were accepted:

"branding_logo_url": "https://cdn.yourbrand.example/logo.svg",
"branding_accent_color": "#1D4ED8",
"branding_source": { "logo": "payload", "accent": "branding_config" }

Separately, branding_config.mode (returned as branding_mode) selects the theme treatment: branded (MVM look), clean (neutral, no MVM gradient) or whitelabel (theme derived from your accent). Like embed_mode, this is admin-configured.

The embed calls this for you on load. Call it directly only to test a signature from your own backend, or to pre-flight credentials in CI.

POST https://awfrtgkoramnvpsvrjjv.supabase.co/functions/v1/partner-verify-session
Content-Type: application/json

{
  "client_id": "pk_partner_demo_0000000000000000",
  "payload": "{\"partner_external_user_id\":\"user-123\",\"email\":\"user@example.com\",\"timestamp\":\"2026-09-02T13:45:00.000Z\"}",
  "signature": "<lowercase hex hmac of that exact payload string>"
}

Here payload is the raw JSON string you signed (a JSON object is also accepted and re-serialised, which will usually break the signature — send the string). Base64 is only used in the iframe URL parameter.

200 OK

{
  "session_token": "6d638412...cef6",              // opaque, send in request bodies
  "session_expires_at": "2026-09-03T01:47:56.107Z",// 12h from creation, extended on activity
  "linked_user_id": "5f521ef7-...",                // partner_linked_users.id
  "internal_user_id": "4a96ecc1-...",              // resolved MVM auth user, or null
  "partner_id": "acec8b73-...",
  "partner_name": "Rights Hub",
  "embed_mode": "workspace",                       // "workspace" | "catalog"
  "branding_logo_url": null,
  "branding_accent_color": null,
  "branding_source": { "logo": "none", "accent": "none" },
  "partner_type": "purchase",                      // "purchase" | "platform"
  "monthly_download_limit": 1,
  "branding_mode": "whitelabel",                   // "branded" | "clean" | "whitelabel"
  "discount_percentage": 0                         // display only; price is recomputed server-side
}

Sessions last 12 hours and are extended on activity. Every subsequent partner API call passes session_token in the JSON body (not as a header), and every call that grants value re-validates the token against the database, so a revoked or expired session stops working immediately even mid-edit.

Every failure is JSON { "error": "<message>" } with a meaningful status code. The strings below are exact and stable — branch on status first, message second. All of these were verified against the live endpoint.

Note that an invalid signature returns 403, not 401, and identity resolution failures are non-fatal: if we cannot resolve or create an MVM auth user from the email, the session is still returned with internal_user_id: null rather than an error.

Entitlement is resolved host-side and is authoritative. A partner cannot grant it. There is no payload field, no header and no session flag that makes a video owned. Every resolution re-derives ownership from our own records — completed orders, membership claims, per-video add-on grants, admin overrides — keyed to the MVM user your payload resolved to. The editor inside the iframe treats what the host sends as final and re-asks at export time; it never decides ownership itself.

What a non-entitled user actually sees today

• They can search the whole catalogue, open any video, and pull clips onto the timeline. Nothing is hidden from browsing because of entitlement.
• Media for an unowned clip is served at preview grade (quality: "preview", the same preview the public site plays). No master and no signed download URL is minted — s3Url is null. Bucket/key identifiers are still passed for scene-cut lookup only, so a preview clip can still be split on real cut points.
• Editing is fully unlocked, including multi-clip edits. The purchase decision is deferred to export time: on export we quote every timeline source the user has not paid for and the export is blocked until those are bought.
• In workspace mode the purchase runs as a modal checkout over the embed, one video at a time in a queue; each success unlocks that source immediately without reloading the editor. A user with no owned sources sees export disabled with a purchase CTA rather than an error.
• A video that has no preview at all, no source file, or is unavailable/sold-out comes back as { status: "unavailable", reason } and cannot be added — the reason string is shown to the user.

Practical consequence for you: never build UI that promises a download based on your own records. Ask, then render what we return.

Read this first: the message contract below is between our embed page (the host, running inside your iframe) and the Workspace editor iframe it mounts. Your host page implements none of it. We do not post messages to your page and we do not listen for messages from it — your only integration surface is the signed embed URL. It is documented here because partners embedding the Workspace ask what the surface does, and because it defines exactly which actions are available in each mode.

{
  "type": "VIDEO_DATA",
  "payload": {
    "videoId": "",                  // empty in a sourceless workspace boot
    "vimeoUrl": "", "s3Url": "",    // keys always present; empty until a source is picked
    "s3Bucket": "…", "s3Key": "…",  // lookup identifiers only (scene cuts)
    "sessionMode": "catalog",       // "video" | "catalog" (catalog = no source yet)
    "hasSource": false,
    "userId": "<mvm auth user id>",
    "metadata": { "title": "", "artist": "", "duration": 0, "width": 1920, "height": 1080 },
    "currentUser": { "id": "…", "email": "…" },
    "permissions": {
      "canExport": false,
      "entitlementSource": "none",  // membership | purchase | addon | admin | none
      "hidePurchaseCta": false,
      "exportCtaLabel": "Purchase to export"
    },
    "ownedVideoIds": [],            // authoritative per-source purchase entitlement
    "ownership": "preview",         // "owned" | "preview" for the selected video
    "deliverables": { /* per-deliverable entitlement + price */ },
    "authToken": "<short-lived HS256 JWT>",
    "accessToken": "<same>",
    "projects": [], "relatedVideos": [],
    "capabilities": {
      "canSwitchProject": true, "canSwitchVideo": true,
      "canExit": false,           // partner embeds are the whole page
      "catalogSearch": true, "catalogPreviewSources": true, "catalogSongMatch": true,
      "exportPurchaseGate": true,
      "addonDeliverables": false, // partner checkout carries no add-ons yet
      "accountNavigation": false
    },
    "partner": {
      "partnerId": "…", "name": "Rights Hub",
      "logoUrl": null, "accentColor": null,
      "embedMode": "workspace"
    },
    "hostMode": "partner"           // "consumer" on the main site
  }
}