API use case: Embedding Remote Control in your own portal

mambo EMM lets you embed a live Remote Control session for a managed device directly inside your own web application — a customer support portal, an internal help-desk tool, or a partner-facing dashboard — without rebuilding the streaming experience yourself.

This is done through a small, purpose-built endpoint that mints a short-lived, single-use embed URL. You load that URL in an <iframe> and your support agents get the full Remote Control surface (screen mirroring plus the on-screen controls) inside your product.

Why not just iframe the console directly? The embed endpoint is designed so your long-lived team access token never touches the end user's browser. Your backend mints a disposable URL bound to a single device, valid for a 90-second handoff window, and hands only that to the browser. This keeps your API credentials on the server where they belong.

How it works

The flow is a machine-to-machine handoff: your server authenticates with an access token and mints a URL, then your frontend renders it.

Your support agent opens a device's support screen in your app.
Your backend calls the mambo EMM API to mint an embed URL, authenticating with your access token.
mambo EMM returns a URL containing a one-time opaque token (not your access token).
Your frontend loads that URL in an <iframe>.
The embed page establishes the Remote Control session and streams the device to your agent.

Prerequisites

Before you start, make sure you have:

Your Team ID.
An access token with the Can remote control devices permission (see permissions below).
The Device ID of the device you want to control. This is the device's unique ID — you can obtain it from the devices list endpoint (GET .../teams/{TEAM_ID}/devices).
The target device must be provisioned for Remote Control — the EMM Companion app installed and its Accessibility permission enabled. See Remote Control for the device-side setup.
Your team's subscription plan must include the Remote Control feature. If it doesn't, the endpoint returns 403 Forbidden.

Required permission

The access token you use must carry the Can remote control devices device command permission (alongside View Devices). See the permissions reference for how these map to token scopes.

Step 1 — Mint an embed URL (server-side)

From your backend, make a POST request to the embed URL endpoint:

POST https://dashboard.mambomobility.com/api/platform/0/v1/teams/{TEAM_ID}/devices/{DEVICE_ID}/remote-control/embed-url
Authorization: Bearer {ACCESS_TOKEN}
Accept: application/json

Path parameter	Description
`{TEAM_ID}`	Your Team ID.
`{DEVICE_ID}`	The MongoDB ID of the target device.

No request body is required.

Response

On success you'll receive 201 Created with:

{
  "embedUrl": "https://dashboard.mambomobility.com/embed/remote-control?token=3f7a1b9e2c4d...&device=60c72b2f9b1d8b001f8b4567&session=ck9x...",
  "expiresIn": 90
}

Field	Description
`embedUrl`	The URL to load in an `<iframe>`. It carries a one-time opaque token — not your access token.
`expiresIn`	The handoff window, in seconds (90). The `<iframe>` must load and connect within this window.

Possible errors

Status	Meaning
`400`	Invalid device ID format.
`401`	Missing or invalid access token.
`403`	Token lacks the Remote Control permission, or the team's plan doesn't include Remote Control.
`404`	Device not found, or the device doesn't belong to the specified team.

Step 2 — Render the embed URL in an iframe

Hand the embedUrl to your frontend and load it in an <iframe>. The embed page is designed to be framed from any origin.

<iframe
  src="https://dashboard.mambomobility.com/embed/remote-control?token=...&device=...&session=..."
  title="Remote Control"
  allow="clipboard-read; clipboard-write"
  style="width: 100%; height: 100%; border: 0;"
></iframe>

The page renders a loading state while the session is established, then shows the live device screen and the on-screen controls (Back, Home, Recents, Lock, Screenshot, and so on — the same controls documented in Remote Control).

Important: mint on demand, server-side

Mint the URL immediately before you need it. The URL is only valid for a 90-second handoff window (expiresIn), which is the time allowed to load the iframe and establish the connection. Once the session is live it stays connected — it is not limited to 90 seconds.
Never mint from the browser. Minting requires your access token; keep that call on your server. Only the resulting embedUrl should reach the browser.
One URL, one session. Each embed URL is single-use and bound to a single device. Minting a new URL for the same device does not reuse a previous one. To control a different device, mint a new URL for that device.
Sessions have a ceiling. A single Remote Control session has a maximum lifetime (currently one hour) after which it ends automatically. To continue, mint a fresh URL and reload the iframe.
The token self-destructs on the page. The embed page removes the token from the browser URL/history after loading and sends no referrer, so the token isn't leaked to logs, history, or other origins.

The script

Here's a minimal Node.js example that mints an embed URL. In a real integration this runs on your backend and returns embedUrl to your frontend over your own authenticated channel.

// This requires an access token with "Can remote control devices" (and "View Devices") permissions.
const ACCESS_TOKEN = "XXXXX";

// Your Team ID.
const TEAM_ID = "XXXXX";

// The MongoDB ID of the device you want to control.
const DEVICE_ID = "XXXXX";

const BASE_URL = "https://dashboard.mambomobility.com/api/platform/0/v1";

async function mintEmbedUrl() {
  const url = `${BASE_URL}/teams/${TEAM_ID}/devices/${DEVICE_ID}/remote-control/embed-url`;

  const res = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
      Accept: "application/json",
    },
  });

  if (!res.ok) {
    throw new Error(
      `Failed to mint embed URL: ${res.status} ${await res.text()}`,
    );
  }

  const { embedUrl, expiresIn } = await res.json();
  console.log(`Embed URL (valid for ${expiresIn}s):`);
  console.log(embedUrl);

  // In your app: return `embedUrl` to the frontend, which loads it in an <iframe>.
  return embedUrl;
}

mintEmbedUrl().catch((err) => console.error(err));

Notes

Mint a fresh URL for each session — don't cache or reuse embed URLs.
If the iframe shows an error or fails to connect, the most common causes are an expired URL (more than 90 seconds elapsed since minting) or a device that isn't provisioned for Remote Control.
The endpoint is available in the interactive API reference under Developers / Remote Control.

How it works​

Prerequisites​

Required permission​

Step 1 — Mint an embed URL (server-side)​

Response​

Possible errors​

Step 2 — Render the embed URL in an iframe​

Important: mint on demand, server-side​

The script​

Notes​