VirtualBox API — part 1: SOAP, sessions and security

The VirtualBox API allows integrating the hypervisor with inventories, automation tools, and custom dashboards. Before writing code, it's worth understanding the role of the SOAP service, how objects are identified, and why authentication, sessions, and security are part of the integration.

This is part 1: the fundamentals of the API, with a focus on remote access through the web service. In part 2, we implemented a client in Go to list virtual machines.

API, VBoxManage, and web dashboard are not the same thing

The VBoxManage offers command-line administration. The web service exposes VirtualBox interfaces through SOAP, enabling HTTP calls with structured XML. A dashboard like the phpVirtualBox is above this integration.

The service vboxwebsrv receives SOAP calls. It should not be confused with a REST API that receives JSON. An application can offer REST to its own consumers and translate those requests into SOAP calls on the backend.

Cliente → SOAP/HTTP → vboxwebsrv → API do VirtualBox → VMs
     ↓
Saída definida pela aplicação

The SDK and the WSDL contract

The WSDL describes operations, parameters, namespaces, and responses of the web service. This contract guides the client's implementation; method and field names should not be inferred from an imagined REST API.

The operations and their parameters were verified against the WSDL included in the official SDK 7.2.0, used as documentary reference for the line 7.2. This is not a recommendation to install an old patch: use a maintained version of VirtualBox and check the SDK corresponding to your environment.

Preparing the service with restricted access

You need VirtualBox with vboxwebsrv available on the host and the service authentication configured. The service executable belongs to the VirtualBox package; downloading the SDK alone does not install the server. The official SDK reference describes its options and authentication.

On the lab host, run as the user responsible for the environment, not as root. If the service is not yet active, a foreground start bound only to loopback is:

vboxwebsrv --host 127.0.0.1 --port 18083

Do not disable authentication to make the example work. The username and password used in the SOAP login must match the authentication mechanism configured on the service, which is not necessarily identical across all installations.

The web service uses HTTP without encryption by default and usually binds to localhost. For access between machines, use TLS configured properly or a protected tunnel; do not publish the port directly on the internet. Oracle also recommends running the service as a regular user. Security guide.

A lab option is to open this tunnel on the computer where the client will run:

ssh -N -L 18083:127.0.0.1:18083 usuario@host-virtualbox

Replace user and host. The client will keep using http://127.0.0.1:18083/, but the transport between computers will stay inside SSH. If the local port is already in use, pick another one and adjust VBOX_URL.

Understanding references, UUIDs, and sessions

A SOAP reference is an object identifier used by the service during the session; it is not necessarily the VM's UUID. A read-only inventory flow is:

Do not persist SOAP references as if they were permanent IDs. To relate data in an inventory, use the returned UUID. For the next run, open a new session and obtain valid references again.

And what about starting VMs, creating snapshots, or changing settings?

This is the next level of integration, not just swapping the method name. Write operations must respect the states, locks, machine sessions, and progress tracking defined by the API. The web service login and a session used to lock a machine should not be treated as the same concept.

My recommendation is to implement each operation separately, with authorization, confirmation when destructive, testing, and reconciliation after failure. An account capable of querying may also have other powers on the server; the fact that a client only queries does not reduce the privileges of the credential.

For a dashboard with Echo and Vue, keep this adapter separate from the HTTP handlers. Do not let the browser freely choose the endpoint, SOAP method, and arguments. Define explicit services, such as listing machines, and control destinations and permissions on the backend.

From theory to a testable integration

Start with a small operation: authenticate, get the machines, query their attributes, and end the session. Validate the contract, handle SOAP failures, and avoid logging credentials. Only afterward, add commands that change the state of the VMs.

At part 2: VirtualBox API in Go, you will find the complete client files, JSON output, timeouts, and automated tests. To learn about a dashboard that uses this integration, also see the article about phpVirtualBox.