Integration Architecture

Use this page when you are designing a customer portal, operations dashboard, or backend integration that depends on Luxonis Hub. It explains the default architecture for production integrations and where authentication, control-plane API calls, and browser session bootstrap should live.

Canonical architecture

For most production deployments, Luxonis Hub should sit behind your own product backend rather than acting as the primary frontend auth boundary.The default integration model is:

Customer users authenticate to your product.
Your frontend calls your backend.
Your backend calls Luxonis Hub APIs and browser-session bootstrap operations.
Your frontend receives only the derived payload it needs for rendering, control, or device sessions.

Keep these rules explicit:

Customer auth stays between your users, your frontend, and your backend.
Hub API keys stay in your backend or server-side tooling only.
The browser should never receive a Hub API key.

Typical integration flow

This is the most common practical shape for a customer-facing Hub integration:

A user opens your customer portal or internal operations UI.
Your frontend requests device state, app state, or session access from your backend.
Your backend calls Luxonis Hub GraphQL and, when needed, session-bootstrap operations.
Your backend returns only the application data or connection payload your frontend needs.
Your frontend renders the result or opens the remote session.

This keeps authentication and Hub credentials on the server side while still allowing direct browser-side session transport where needed.

Public API split

Luxonis Hub currently exposes two customer-facing API styles:

GraphQL control API for devices, apps, snaps, control-plane reads, mutations, and browser-session bootstrap.
REST models API for advanced model registry and conversion automation.

That split is normal. If your product uses both fleet control and model-management workflows, you will integrate with both.For external GraphQL integrations, use the public team { ... } surface.

Browser session bootstrap

For browser-side device and app sessions, your backend should call the GraphQL control API and return the bootstrap payload to the frontend.Relevant GraphQL operations include:

requestDeviceWebrtcConfig for device sessions such as Web Terminal and live logs
requestDeviceAppConnection for app and visualizer sessions through oak-webrtc

This keeps Hub credentials on your backend while still letting the browser connect directly to the remote session transport.

Frontend rendering guidance

For customer portals, the recommended rendering primitive is the visualizer.Use visualizer when you need:

live video
detections and overlays
richer outputs such as point clouds

Treat fully custom rendering as the advanced/custom path for cases where visualizer is not a fit.Direct same-LAN websocket or device-local access can still be useful as a fallback path, but it is not the canonical remote integration model for customer portals.

Current product boundaries

Keep these boundaries explicit in your integration design:

Hub API keys are full-access team secrets today.
Use the official GraphQL guides and reference pages together with schema inspection.
Webhooks are not yet a broad stable public integration surface.
Manifest-based rollout and large-scale deployment orchestration are not available today.
Self-hosted host operating systems remain customer-managed.

Next steps

About GraphQL

Understand the public team { ... } request shape used for control-plane integrations.

Streaming and Visualizer

Use the recommended backend-mediated bootstrap flow for browser sessions and customer portals.

Device Management

Start with the public read path for listing and inspecting devices.

Models API

Use the separate models API for advanced model registry and conversion automation.

ON THIS PAGE