Federated Tokens

A federated token is a short-lived credential your server mints with its own credential and hands to code you don't trust with that credential: a web page, a mobile app, a video player, or a client talking to a camera on your local network. The token acts with the same organization and role as the credential that minted it, until it expires or that credential is revoked.

Mint a token

Call POST /api/org/generateFederatedSessionToken from your server:

curl -X POST "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"durationSec": 3600, "deviceUUid": "CAMERA_UUID"}'

// Your backend: authenticate your own user first, then mint a token for the page they're using.
app.post("/api/federated-token", requireUser, async (req, res) => {
  const r = await fetch(
    "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken",
    {
      method: "POST",
      headers: {
        "x-auth-scheme": "api-token",
        "x-auth-apikey": process.env.RHOMBUS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        durationSec: 3600,
        deviceUUid: req.body.cameraUuid,
        domain: "https://app.example.com", // the origin of the page that uses the token
      }),
    },
  );
  if (!r.ok) return res.status(502).json(await r.json());
  const { federatedSessionToken, expiresAtMs } = await r.json();
  res.json({ federatedSessionToken, expiresAtMs });
});

import os
import requests

res = requests.post(
    "https://api2.rhombussystems.com/api/org/generateFederatedSessionToken",
    headers={
        "x-auth-scheme": "api-token",
        "x-auth-apikey": os.environ["RHOMBUS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"durationSec": 3600, "deviceUUid": "CAMERA_UUID"},
)
res.raise_for_status()
body = res.json()
token = body["federatedSessionToken"]
expires_at_ms = body["expiresAtMs"]

Response:

{ "federatedSessionToken": "AAAAAAAAAAAAAAAAAAAAAA", "expiresAtMs": 1792371600000 }

Fields

You can mint with an API key, an OAuth access token (the token acts as the signed-in user), or a partner credential plus x-auth-org (the token belongs to that client organization). A federated token can't mint another federated token (403), and console (browser) sessions can't mint federated tokens.

Use a token

Send the scheme and the token as x-auth-scheme: federated-token and x-auth-ft: <token>, as headers or as query parameters. The same two values work everywhere:

Browsers can't set headers on an <img>, a <video> or a WebSocket, so put both values in the URL there:

<!-- A camera snapshot in a web page -->
<img src="https://media.rhombussystems.com/media/CAMERA_UUID/MEDIA_REGION/snapshot.jpeg?x-auth-scheme=federated-token&x-auth-ft=TOKEN" />

Media and streams shows each kind of media URL with the token attached, including HLS, DASH and WebSocket players.

The domain field

domain binds a token to one web origin. A token with a domain works only when the request's Origin header matches it or, when the request has no Origin, its Referer. Anything else, including a request with neither header, gets 403 DOMAIN_NOT_ALLOWED. Rhombus checks this on the REST API, the media hosts and the event WebSocket. A token without a domain isn't checked.

Browsers send Origin on fetch calls, cross-origin requests and WebSocket handshakes, and a Referer on images and video unless the page's referrer policy suppresses it. Servers, native players and mobile apps usually send neither.

When you mint, domain must be an absolute http or https origin, such as https://app.example.com. A value that isn't one (example.com, .example.com) is rejected with 400.

Which to use:

domain limits use from a browser; it doesn't protect a stolen token, because anything outside a browser can send whatever Origin or Referer it likes. Short lifetimes, deviceUUid and revocation are what limit a leaked token.

Lifetime and refresh

• A token works until expiresAtMs: durationSec after it was minted, one hour by default and at most 24 hours. Rhombus's own device apps (TV, video wall, kiosk, keypad and door station) can mint tokens of up to 30 days; no federated token lasts longer than 30 days.
• A token stops working early when the credential that minted it is revoked: the API key is deleted, the OAuth grant is revoked, or the mobile app session ends. You can also revoke a token yourself.
• Cameras on your LAN cache a successful check, so a token can keep working there for up to a minute after it expires.
• Tokens are region-bound: a token minted on US hosts works only on US hosts.

Refresh before expiry from your backend. A client that got a one-hour token asks for a new one at about 54 minutes and swaps it into its URLs:

async function getToken() {
  const r = await fetch("/api/federated-token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ cameraUuid }),
  });
  const { federatedSessionToken, expiresAtMs } = await r.json();
  setTimeout(getToken, (expiresAtMs - Date.now()) * 0.9); // renew at 90% of the remaining lifetime
  useToken(federatedSessionToken);
}

The React SDK does this for you: it calls your backend's token endpoint and renews the token before it expires.

Revoke a token

To end a token before it expires, for example when your user signs out, call POST /api/org/revokeFederatedSessionToken with the token. Call it with any credential of the token's organization: the federated token itself (so a browser can revoke its own token when its user signs out), your server's API key, or an OAuth token; the browser console session can't. It only revokes tokens of the caller's organization and always returns 200, whether or not the token was still valid, so it's safe to call on every sign-out:

curl -X POST "https://api2.rhombussystems.com/api/org/revokeFederatedSessionToken" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"federatedSessionToken": "TOKEN"}'

Security checklist

• Mint on your server only. Never put the API key that mints tokens in a browser or app.
• Mint with a credential whose role covers only what the client needs; the token inherits that role. See Permissions and key rotation.
• Use deviceUUid whenever the client needs one camera.
• Set domain to your page's origin for tokens used in a web page.
• Keep durationSec short, refresh before expiresAtMs, and revoke tokens when your user signs out.
• Treat a token like a password while it lives: don't log it, and don't put token-bearing URLs in analytics or error reports.