Partner Engineering

Embed XVIVO Insights in your platform with a signed, short-lived launch flow.

This guide is for partner engineers integrating the embedded Insights experience into an existing portal or website. Your frontend hosts the iframe. Your backend owns launch signing. XVIVO validates the launch, creates the scoped session, and serves the embedded viewer.

Back to Demo Host Current Partner: FlowHawk (flowhawk)

Integration Model

The partner platform remains the entry point. When a user opens Insights for a device, the partner frontend calls the partner backend. That backend creates or requests a secure launch URL using the agreed partner identity and shared signing secret. The frontend then places the resolved embedded URL into an iframe.

Partner Frontend

Renders the iframe, calls the partner backend, and optionally auto-resizes the iframe using the embedded page height messages.

Partner Backend

Builds the canonical string, signs it with HMAC-SHA256, follows the SSO redirect, and returns the final iframe URL.

XVIVO Insights

Validates the signed launch, issues a one-time code, exchanges it for a session token, and serves the embedded viewer.

Company Scope

Launches are validated against a company-scoped service account in the Insights backend and are rejected if the backend-resolved device company does not match.

Partner Configuration Package

These are the values that define a partner integration. Some are safe to discuss in operational onboarding. Others are confidential and must stay on the server side only.

Operational Values

Display name: FlowHawk
Slug: flowhawk
Contact email: insights@flowhawk.com
Active: Yes
Timestamp window: 60 seconds
One-time code TTL: 60 seconds

Confidential Values

Shared HMAC secret: stored server-side only and never exposed in browser code.
Service account: flowhawk-019db539-c148-72e0-8be0-eef16b0e3ff6@xvivoinsights.internal
Provision username: flowhawk-viewer@partner.com
Provision company ID: 019db539-c148-72e0-8be0-eef16b0e3ff6

Allowed iframe host domains

https://flowhawk.up2technology.com
http://localhost:5600

Do not place the HMAC secret, raw signatures, or full signed launch URLs in client documentation or browser-side code. Those belong in the engineering handoff and server-side configuration only. In remote mode, treat the configured company values on this page as expected integration scope, not as live company data returned by SSO.

Backend Request Flow

The browser should never generate the signed launch URL. Treat the partner backend as the launch authority.

Authoritative company resolution happens in the Insights SSO backend during launch validation. The backend derives company scope from the requested device and the resolved service account, then rejects the launch if they do not match.

Frontend requests a launch URL

The partner frontend sends the selected device serial number to a partner-owned backend endpoint such as /api/insights/launch.

Backend creates the signed SSO request

The backend generates ts and nonce, then signs the canonical string using the partner slug and shared HMAC secret.

Backend resolves the redirect

The backend calls the XVIVO SSO endpoint and follows the redirect to the final embedded app URL instead of returning the raw API endpoint to the browser.

Frontend loads the iframe

The frontend sets the returned iframeSrc value on the iframe and then listens for resize messages from the embedded page.

Embedded app establishes the session

The embedded viewer exchanges the one-time code for a scoped session token, loads run data, then subscribes to live updates.

Required params: partnerSlug Required params: deviceSerialNumber Required params: ts Required params: nonce Required params: sig

Signing Format

Build the canonical string from the sorted fields below, then compute an HMAC-SHA256 signature with the shared secret.

deviceSerialNumber=KiAsT-2400-0087
nonce=<generated nonce>
partnerSlug=flowhawk
ts=<ISO 8601 UTC timestamp>

Canonical string:
deviceSerialNumber=KiAsT-2400-0087&nonce=<generated nonce>&partnerSlug=flowhawk&ts=<ISO 8601 UTC timestamp>

GET https://xvivo-api-test.up2technology.com/api/v1/identity/sso?partnerSlug=flowhawk&deviceSerialNumber=KiAsT-2400-0087&ts=<timestamp>&nonce=<nonce>&sig=<hmac-sha256>

Example Frontend iframe Integration

The example below matches the host page behavior already used in this demo. The browser only asks for a launch URL, then loads the iframe.

<iframe
  id="insightsFrame"
  title="XVIVO Insights"
  style="width:100%; min-height:720px; border:0;"
  sandbox="allow-scripts allow-same-origin allow-forms">
</iframe>

<script>
  async function openInsights(deviceSerialNumber) {
    const response = await fetch('/api/insights/launch', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ deviceSerialNumber })
    });

    if (!response.ok) {
      throw new Error('Failed to get launch URL');
    }

    const data = await response.json();
    document.getElementById('insightsFrame').src = data.iframeSrc;
  }

  window.addEventListener('message', event => {
    const data = event.data;
    if (!data || data.type !== 'flowhawk-embed-height') return;

    const frame = document.getElementById('insightsFrame');
    frame.style.height = Math.max(720, data.height) + 'px';
  });
</script>

Example resolved iframe source: https://xvivo-test.up2technology.com/embedded/run?code=<one-time-code>&deviceSerialNumber=<device-serial>&runId=<optional-run-id>

Example Backend Endpoint

This is the simplest backend contract to expose to the partner frontend. Keep the HMAC secret and signing logic behind this endpoint.

POST /api/insights/launch
Content-Type: application/json

{
  "deviceSerialNumber": "KiAsT-2400-0087"
}

Response:
{
  "iframeSrc": "https://xvivo-test.up2technology.com/embedded/run?code=<one-time-code>&deviceSerialNumber=<device-serial>&runId=<optional-run-id>"
}

Server-side pseudocode:
1. Load partner slug and shared HMAC secret from configuration
2. Generate ts in ISO 8601 UTC format
3. Generate nonce
4. Build canonical string
5. Sign with HMAC-SHA256
6. Call the XVIVO SSO endpoint
7. Resolve the redirect to the embedded route
8. Return the final embedded URL as iframeSrc

Validation Rules and Failure Cases

A signed launch is accepted only when every validation step passes. Common failures are deterministic and should be handled as supportable integration errors.

Validation Rules

All required URL parameters must be present.
The partner slug must be known and active.
The HMAC signature must match.
The timestamp must still be within the accepted window.
The nonce must not have been used before.
The device must exist and resolve to a company.
The service account must be active and have role CompanyViewer.
The device company must match the service account company.

Common Failure Codes

invalid_signature
link_expired
link_used
unknown_partner
integration_not_allowed
wrong_role
unknown_device
company_mismatch