License Hub Appliance API Operations Index

Get Backup Config

Returns saved remote backup server (SFTP) settings used by Backup and Restore. 204 if none configured.

Update Backup Config

Saves remote backup server settings; include current _revision from GET when updating.

Get Recurring Backup Config

Returns scheduled (recurring) backup policy. 204 if not configured.

Update Recurring Backup Config

Saves scheduled backup policy; set weekly or interval fields to match backup_schedule_type.

Start Backup

Starts an on-demand backup; poll GET /sspi/backup/status/{id} using the id from the 202 response.

Get Backup Status

Returns one backup job by id (from POST /sspi/backup or GET /sspi/backup/status).

Get Backup Status History

Lists backup jobs (newest first). Use page_size=1 with no filters to fetch only the latest job; result may be empty if no backups exist.

Get Backup Details

Returns extended backup metadata (including instance details at backup time) for one backup job id.

Start Restore

Starts restore from backup_id; poll GET /sspi/restore/status/{id} using the id from the 202 response.

Get Restore Status

Returns one restore job by id (from POST /sspi/restore or GET /sspi/restore/status).

Get Restore Status History

Lists restore jobs (newest first). Optional status filter narrows by job state.

Diagnostic

Get Platform Health Status

Returns the overall high-level health state of the platform deployment as perceived by the installer.

Notes:

This is an installer-centric view of health. For detailed, granular cluster health metrics, use the ssp/cluster/monitor/platform/status API from the corresponding Platform instead.

Get Installer Info

Returns diagnostic information about the Platform Installer appliance itself.

Returns:

FQDN of the installer appliance.
Active software version of the installer.
Current operational status of the installer daemon.

Notes:

This endpoint is independent and does not require any deployed Platform instances to function.

Instance Management

Get Deployment Settings

Fetches the global configuration settings based on the platform instance type and its supported form factors. Either form_factor or ssp_type must be provided, ssp_type parameter represents the platform instance type.

For MEDIUM form factor:

min_worker_count: 2
max_worker_count: 2
Note: Medium supports exactly 2 workers. Use Large form factor for 4+ workers

For LARGE form factor:

min_worker_count: 4
max_worker_count: 13

For EXTRA_LARGE form factor:

min_worker_count: 8
max_worker_count: 17
Note: For high-scale deployments with all features

For instance type parameter:

LICENSING: Licensing deployment (form_factor is SMALL, worker_count: 1)
AVI_OPERATIONS: AVI Operations deployment (form_factor is SMALL, worker_count: 2)
ATP: Advanced Threat Protection (requires form_factor parameter)

IP Pool Count Calculation: The API returns minimum IP pool counts (min_node_ip_pool_count and min_service_ip_pool_count) based on the form factor and worker count.

For variable worker count form factors (Medium, Large, Extra-Large):

worker_count parameter can override the default (must be within valid range)
If not provided, min_worker_nodes from the form factor spec is used

For fixed worker count instance types (LICENSING, AVI_OPERATIONS):

worker_count parameter is ignored
Always uses min_worker_nodes from the deployment spec

Node IP Pool (all deployments): 2 + controller_count + worker_count (1 for VIP + 1 for rolling upgrade + all node IPs)

Service IP Pool (varies by deployment type):

LICENSING/AVI_OPERATIONS: 3 IPs (1 Contour + 1 kafka-external + 1 kafka broker, no scaleout)
Medium: 5 IPs (1 Contour + 1 kafka-external + 3 kafka brokers hardcoded)
Large/Extra-Large: 3 + ceil(worker_count/2) (1 Contour + 1 kafka-external + 1 kafka broker + extra brokers for Kafka cluster)

Delete Platform

Triggers the asynchronous undeployment and teardown of the specified platform cluster.

Behavior and Side Effects:

Executing this endpoint will immediately begin destroying the underlying Kubernetes cluster, VMs, and associated resources.
The workflow is asynchronous. The status endpoint will reflect the teardown progress.
Upon successful completion of the undeployment workflow, the platform record is deleted and subsequent calls to the status endpoint will return a 404 Not Found.

Actions:

Passing action=force_delete will bypass graceful teardown steps and forcibly delete the Platform deployment and database records, ignoring standard cleanup failures.

Get Platform Config

Retrieves the complete, detailed configuration specification for a specific platform deployment. This includes compute, network, service, and system configurations.

Update Platform Config

Updates the LicenseHub configuration and triggers the appropriate Lifecycle Management (LCM) workflow asynchronously.

Behavior:

Fresh Platform (Not Deployed): If the platform record exists but the cluster hasn't been deployed yet, this updates the configuration and immediately triggers the initial deployment workflow.
Deployed Platform (Day-2 Operation): If the LicenseHub is already running, this saves the updated configuration and triggers a Day-2 configuration update workflow.

Workflow Chain: The response returns a 202 Accepted with a status_url. Call GET /lh-appliance/platforms/{platform-id}/status to poll the update/deployment progress.

Get Platform Lcm Status

Retrieves the real-time execution status of any active precheck or Lifecycle Management (LCM) workflows for the platform.

Workflow Chain: This endpoint is the standard polling mechanism used after triggering asynchronous operations like POST /sspi/platforms, PUT /sspi/platforms/{platform-id}, or DELETE /sspi/platforms/{platform-id}.

Returns:

Overall status of the active job (IN_PROGRESS, COMPLETED, FAILED, etc.).
Detailed step-by-step precheck results and their individual pass/fail states.

Get All Platforms

Retrieves a paginated list of all LicenseHub platform deployments.

Notes:

If no platforms exist, returns an empty list with a 200 status code.
To get the detailed full configuration of a specific platform returned in this list, use GET /lh-appliance/platforms/{platform-id}.

Create Platform

Creates a new LicenseHub configuration record in the installer and triggers the initial Lifecycle Management (LCM) deployment workflow asynchronously.

Workflow Chain:

Call this endpoint with the full configuration payload to start the deployment.
The response returns a 202 Accepted along with the newly generated platform-id and a status_url.
Use the generated platform-id to call GET /lh-appliance/platforms/{platform-id}/status periodically to monitor the precheck and deployment progress.

Package Management

Get Bundle

Fetches the information about a specific bundle including its upload status, version details, and metadata.

Notes:

Returns 404 if the bundle does not exist or has been deleted

Delete Bundle

Permanently deletes a bundle or cancels an in-progress upload operation.

Notes:

If bundle status is IN_PROGRESS, this will cancel the upload and clean up partial data
If bundle status is READY, this will permanently remove the bundle from storage
Once deleted, the bundle cannot be recovered and will need to be uploaded again
Bundles with status IN_USE or ATTACHED cannot be deleted

Get Bundles

Retrieves a paginated list of all bundles available in installer with their current status and metadata.

Usage:

Use this to discover available bundles before selecting one for deployment
Results are paginated - use the pagination parameters to navigate large result sets

Upload Remote Bundle

Initiates an asynchronous download and import of a bundle from a remote URL onto installer.

Notes:

The remote URL must be accessible from the installer.
Bundle validation occurs during download - invalid bundles will result in FAILED status (broken download, incomplete bundle, bad metadata)
ERROR status is reserved for unexpected internal errors

Upload Local Bundle

Uploads a bundle file directly to installer via multipart form data. The returned response contains a link to the bundle status endpoint.

Notes:

File validation and extraction occurs during upload
Invalid bundles will result in FAILED status with diagnostic message

Get Depot Health

Performs a lightweight health check on the package management service to verify that it is operational.

Sspi Upgrade

Get Version Summary

Retrieves the current versions of appliance components and the target upgrade version. The current version reflects the actually installed version on the appliance. After a successful upgrade (e.g., 5.1.1 to 5.2.0), the current version updates to the new version (5.2.0).

The response includes:

Current appliance version
Current Upgrade Manager version
Target appliance version (set when upgrade is initiated)

Get Upgrade Packages

Retrieves the list of available upgrade packages from the depot service and returns the packages eligible for the upgrade after evaluating each available package.

The response includes package version, name, and size for each available upgrade bundle that has been uploaded to the system.

Only packages eligible for the upgrade are returned.

Get Sspi Upgrade History

Retrieves the upgrade history of the system.

The list is sorted in descending order by start time, with the most recent upgrade first. The history includes the current upgrade if one is in progress.

Note: Upgrade Manager upgrades are not included in this history. Only full appliance upgrades (initiated by the user) are tracked.

List Upgrade Manager Steps

Retrieves the list of all Upgrade Manager upgrade step definitions. This endpoint returns metadata about each step in the Upgrade Manager upgrade process, enabling the UI to display the steps to the user.

The Upgrade Manager is the service that orchestrates appliance upgrades. It must be upgraded to the target version before the main appliance upgrade can proceed.

The Upgrade Manager upgrade is typically quick and involves updating the upgrade service binary and UI components.

This endpoint returns step definitions only, not execution status. To retrieve execution status and progress, use GET /upgrade/manager/status.

Trigger Upgrade Manager Upgrade

Upgrades the Upgrade Manager service itself to the target version specified in the request body. This is distinct from POST /upgrade which upgrades the entire appliance - this endpoint only upgrades the upgrade orchestration tool.

The Upgrade Manager must be at the target version before it can orchestrate the main appliance upgrade (POST /upgrade).

Prerequisites:

A valid upgrade package must be uploaded to the system
No other upgrade operation should be in progress

The operation executes asynchronously and returns immediately with a status URL. Use GET /upgrade/manager/status to monitor upgrade progress.

Only one Upgrade Manager upgrade operation can execute at a time (returns 409 if upgrade is in progress or already completed).

If the upgrade fails, this endpoint can be called again to retry the upgrade.

Get Upgrade Manager Status

Retrieves real-time status and detailed progress information for the Upgrade Manager upgrade operation. This endpoint provides visibility into upgrade execution with granular reporting for each upgrade step and an overall progress percentage.

Poll this endpoint at regular intervals while upgrade is in progress.

Upon completion, verify that overall_status is SUCCESS before proceeding with appliance upgrade (POST /upgrade). If status is FAILED, examine the upgrade_steps array for the failed step to identify root cause.

If no Upgrade Manager upgrade has been initiated, the response indicates NOT_STARTED status with progress_percentage of 0.

List Sspi Upgrade Steps

Retrieves the list of all pre-checks and upgrade step definitions. This endpoint provides visibility into the upgrade workflow phases and pre-checks validations that will be executed, enabling the UI to display the upgrade process to the user before execution.

The steps are listed in the order they will be executed during the upgrade process. This endpoint returns step definitions only, not execution status. To retrieve execution status and progress, use GET /upgrade/status.

Trigger Sspi Upgrade

Executes the appliance upgrade operation to transition the system to the target version based on the specified action. This asynchronous operation orchestrates the complete upgrade workflow including management cluster, workload clusters, and appliance VM.

Supported actions:

PRECHECKS_ONLY: Runs only pre-upgrade validation checks without performing the upgrade. This operation is idempotent and non-disruptive; it can be safely run on a live production system to assess readiness before a maintenance window. PRECHECKS_ONLY is only allowed when the upgrade status is NOT_STARTED. Only one pre-checks operation can run at a time.

START: Runs pre-checks followed by the full upgrade. This is the standard upgrade flow. START is only allowed when the upgrade status is NOT_STARTED. Requires a scheduled maintenance window as the appliance VM will reboot during the upgrade, causing temporary unavailability of the management interface. Ensure a backup is taken before initiating. Do not interrupt the upgrade process once initiated unless absolutely necessary for emergency recovery.

CONTINUE: Starts the upgrade without running pre-checks. CONTINUE is only allowed when the upgrade status is NOT_STARTED and pre-checks have completed successfully, returns an error for any other state.

RETRY: Resumes the upgrade workflow from the failed step. Already completed upgrade steps are skipped automatically. RETRY is only allowed when the upgrade status is FAILED, which means pre-checks have already passed. If pre-checks failed, use START again.

Prerequisites:

Upgrade Manager must be upgraded to target version (POST /upgrade/manager?action=upgrade)
A valid upgrade package must be available

Recommended workflow:

Check versions (GET /upgrade/version-summary), review packages (GET /upgrade/packages), and upgrade the Upgrade Manager (POST /upgrade/manager).
Run pre-checks (POST /upgrade?action=PRECHECKS_ONLY) and review results (GET /upgrade/status).
During a maintenance window, start the upgrade (POST /upgrade?action=START or POST /upgrade?action=CONTINUE if pre-checks already passed), and monitor progress (GET /upgrade/status).
If upgrade fails, address the issue and retry (POST /upgrade?action=RETRY).
Review upgrade history (GET /upgrade/history) after completion.

Get Sspi Upgrade Status

Retrieves real-time status and detailed progress information for the upgrade operation. This endpoint provides visibility into upgrade execution with granular reporting for each upgrade phase.

Poll this endpoint at regular intervals while upgrade is in progress.

Upon completion, verify that overall_status is SUCCESS. If status is FAILED, examine the upgrade_steps array for the failed step to identify root cause or connect with VMware Support for assistance.

If no upgrade has been initiated, the response indicates NOT_STARTED status.

Note: During the appliance VM upgrade phase, the system will reboot and this endpoint may be temporarily unavailable. Resume polling after the system comes back online.

User Management

Login

Authenticates a user against Installer and starts a session. This is the entry point for all other Installer APIs - every subsequent request must present the credentials returned here.

How to use the response:

On success, the Set-Cookie response header contains the session cookie and the X-XSRF-TOKEN response header contains the XSRF token. Send the cookie value in the Cookie request header and the token value in the X-XSRF-TOKEN request header on every subsequent request.
The roles returned in the response body determine which of the other Installer APIs this user is authorized to call (see the security requirements on each operation).

Notes:

If the user's password has expired, the API returns 302 and redirects to the change-password flow instead of returning 200. Call POST /iam/change-password before retrying login.

Logout

Invalidates the caller's current session. The session cookie obtained from POST /iam/login is no longer valid after this call succeeds, and a new login is required to make further authenticated requests.

Change Password

Changes the password of the currently authenticated local user. This is a self-service operation - a user can only change their own password, and must provide their current (old) password to prove ownership.

Notes:

Only local users have a password to change. Remote (LDAP) users manage their password through their identity provider.
To reset another local user's password without knowing their current password, an enterprise_admin must use POST /iam/reset-password instead.

Reset Password

Sets a new password for a local user without requiring their current password. Use this when a local user has forgotten their password; use POST /iam/change-password for the self-service case where the old password is known.

Notes:

Requires the enterprise_admin role.
Remote (LDAP) users do not have a local password and cannot be targeted by this API - their password is managed by the identity provider.

Get Current User Info

Returns the user name, display name, type, and assigned roles of the currently authenticated caller.

Get All Users Info

Returns the users and groups known to Installer, whether defined locally or discovered through a configured LDAP identity source. Use the role and user_type filters to narrow results, for example to find every user who holds the auditor role.

Get All Roles Info

Returns the fixed set of roles that can be assigned to a user or group, along with their display names.

Get All Role Bindings

Returns every user or group that currently has at least one role assigned, together with the roles they hold. The id in each result is the value to use as binding-id when calling GET, PUT, or DELETE /iam/role-bindings/{binding-id}.

Bind Roles To Entity

Creates a new role binding, granting the specified roles to a remote (LDAP) user or remote (LDAP) group. Local users cannot be granted roles through this API. To grant additional roles to an entity that already has a binding, use PUT /iam/role-bindings/{binding-id} instead - this operation always creates a new binding.

Get Role Binding

Returns the role binding identified by binding-id. Obtain the binding-id from the id field of an entry returned by GET /iam/role-bindings.

Update Roles To Entity

Overwrites the set of roles held by the entity identified by binding-id with the roles provided in the request body. This is a full replacement, not a merge - any role currently held but omitted from the request is removed.

Delete Roles To Entity

Deletes the role binding identified by binding-id, removing every role currently held by that user or group. After this call succeeds, the entity retains no access to Installer until a new role binding is created for it.

Get All Ldap Identity Sources

Returns every LDAP identity source configured on Installer, used to authenticate remote users and groups in addition to local accounts.

Create Ldap Identity Source

Configures a new LDAP identity source so its users and groups can authenticate to Installer. Before saving, Installer validates connectivity to the LDAP server; if the probe fails, the request is rejected with 400 and no identity source is created - fix the connection details and retry.

Get Ldap Identity Source

Returns the configuration of the LDAP identity source identified by identity-source-id.

Update Ldap Identity Source

Replaces the configuration of the LDAP identity source identified by identity-source-id. As with creation, Installer validates connectivity to the LDAP server before saving; if the probe fails, the request is rejected with 400 and the existing configuration is left unchanged - fix the connection details and retry.

Delete Ldap Identity Source

Deletes the LDAP identity source identified by identity-source-id. Users and groups that authenticated through this source will no longer be able to log in to Installer, and any role bindings for them become orphaned - remove those separately via DELETE /iam/role-bindings/{binding-id} if they are no longer needed.