Skip to main content
Version: 10

Authenticating and Encrypting the Web Endpoints

MoveIt Pro requires a shared frontend key on the browser-facing backend endpoints: the REST API, the WebSocket bridge (foxglove_bridge), the video stream, the terminal, and the opt-in legacy rosbridge_server compatibility port. Those backend ports are also served over TLS.

Frontend Key​

MoveIt Pro reads the shared key from MOVEIT_FRONTEND_KEY. The backend fails fast if this variable is unset or blank, so deployments cannot accidentally start with a public shared secret. For local-only development, explicitly set the documented dev key (moveit-secret-key) or use the provided local compose defaults.

Upgrading an existing deployment

MOVEIT_API_KEY was renamed to MOVEIT_FRONTEND_KEY. Before starting the new version, update .env files, Compose overrides, systemd units, CI secrets, and other deployment configuration to use the new variable name. The backend does not read the old variable.

For any deployment reachable beyond a trusted local development machine, set a strong key before launching MoveIt Pro:

export MOVEIT_FRONTEND_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
moveit_pro run

Distribute the key only to people and tools that need to reach the deployment. The same key guards every browser-facing backend endpoint.

TLS certificates​

Backend TLS is required. MoveIt Pro uses MOVEIT_TLS_CERT_FILE and MOVEIT_TLS_KEY_FILE when both are set; setting only one is an error. Without an override pair, the backend generates a self-signed certificate once under the persistent MoveIt Pro data directory and reuses it on later starts. Set MOVEIT_TLS_CERT_DIR to relocate that generated pair.

export MOVEIT_TLS_CERT_FILE=/path/to/fullchain.pem
export MOVEIT_TLS_KEY_FILE=/path/to/privkey.pem
moveit_pro run

Self-signed certificates are enough to encrypt frontend-to-backend traffic on a local host-network deployment, but browsers and external clients may need to trust the certificate explicitly.

Direct SDK clients should use a certificate signed by a CA their host already trusts. For isolated development with the generated certificate, copy cert.pem from the persistent TLS directory to the client and add it to that client host's trust store before connecting. On Ubuntu, install the certificate with:

sudo install -m 0644 /path/to/cert.pem /usr/local/share/ca-certificates/moveit-pro.crt
sudo update-ca-certificates

Python/OpenSSL-based clients launched from that host then validate the WSS certificate through the system trust store. Do not disable certificate verification outside isolated development.

Backend TLS does not by itself make the browser-to-frontend page load HTTPS: the packaged nginx frontend still listens on its normal HTTP port unless you run it behind an HTTPS reverse proxy or SSH tunnel. Use that outer TLS layer before exposing the web UI on an untrusted network.

Using the web interface​

Open the web UI as usual. For localhost/loopback development origins, the app sends the documented dev key automatically. For non-local origins, or when a backend rejects the stored/dev key, the UI shows a Frontend key required screen. Enter the deployment's MOVEIT_FRONTEND_KEY and select Connect; it is stored in your browser per backend origin and reused on subsequent visits.

The frontend connects to backend ports with HTTPS/WSS by default. To connect a newer frontend to an older backend that does not serve TLS, set:

export MOVEIT_FRONTEND_ALLOW_INSECURE_BACKEND=true

This compatibility switch affects only the frontend proxy/dev server. The backend itself always serves TLS and does not provide a plaintext opt-out. Vite verifies the backend certificate and hostname by default. For isolated local development only, if the generated certificate is not installed in the host trust store, set:

export MOVEIT_FRONTEND_ALLOW_UNVERIFIED_BACKEND_CERTIFICATE=true

Do not use this certificate-verification opt-out with a remote backend.

Using the endpoints directly​

Direct clients must present the frontend key:

  • REST API — send an Authorization: Bearer <key> header. REST query-string credentials are rejected so the key cannot leak through access logs:

    curl --cacert /path/to/ca.pem \
      -H "Authorization: Bearer ${MOVEIT_FRONTEND_KEY}" \
      https://<certificate-hostname>:3200/objectives

  • WebSocket bridge (foxglove_bridge, port 3201) — clients speaking the Foxglove WebSocket protocol append the key to the connection URL as a query parameter, since WebSocket clients cannot always set request headers:

    wss://<host>:3201/?token=<key>

  • Video stream — append &token=<key> to the stream URL.

  • Legacy rosbridge (--enable-rosbridge, default port 3204) — connect via wss://<host>:3204/?token=<key>.

Security notes​

  • The frontend key is a bearer secret: anyone who has it can reach the endpoints.
  • WebSocket and video clients often carry the key in the URL query string; avoid logging request URLs where possible.
  • The documented moveit-secret-key value is only for local development. Set a deployment-specific key for shared, remote, or production deployments.
  • Backend TLS protects frontend-proxy-to-backend and direct-backend traffic. Use HTTPS or SSH tunneling for the browser-to-frontend hop on remote networks.
  • The backend serves TLS unconditionally. Keep certificates and private keys in a protected location and rotate the frontend key if it is exposed.