HCX Manager Appliance Management APIs Operations Index
All available HCX Manager Appliance Management APIs Operations
Applies SSL/TLS certificate and private key for the HCX Manager's HTTPD web server. This certificate is used for HTTPS connections to the HCX Manager.
Important Notes:
- Validates certificate and private key format
- If private key is not provided, uses the private key from the last CSR generation
- Applies certificate with graceful Apache restart (no service interruption)
Certificate Format:
- Must be X.509 certificates in PEM format
- Can include certificate chain (intermediate + leaf certificates)
- Private key must match the certificate's public key
Retrieves all user-imported trusted certificates from the HCX Manager's trust store. These certificates are used to establish trust with external systems (vCenter, NSX, VCD, etc.).
Imports an X.509 certificate into the HCX Manager's trust store. The certificate can be provided directly as PEM string, via file upload, or fetched from a URL. Certificate is immediately available for use in SSL/TLS connections.
URL validation blocks loopback, link-local, and HCX Manager's own IP and prevents SSRF attacks by blocking internal endpoints
Removes a trusted certificate from the HCX Manager's trust store using its SHA-256 thumbprint.
Unauthenticated API to retrieve a current HCX Manager Certificate as JWT signed with the private key of the HCX Manager's rotated certificate.
Service Types:
admin-mgmt: Admin Portal (9443)service-mgmt: Service/Operations Portal (443)
Controls the Web service. Allows starting or stopping of the Web service. The operation is synchronous and returns the final status after the action completes.
Retrieves the current status of the Web Service
Controls the Application service. Allows starting or stopping of the Application Service. The operation is synchronous and returns the final status after the action completes.
Retrieves the current status of the Application Service
Controls the SSH service. Allows starting, or stopping of the SSH service. The operation is synchronous and returns the final status after the action completes.
Retrieves the current status of the SSH service
Retrieves the current Entitlement Server configuration for license management. Passwords are automatically redacted from the response for security.
Add a new Entitlement Server configuration for license management. Validates connectivity and credentials before saving. Automatically triggers vCenter license discovery job upon successful configuration.
Updates an existing Entitlement Server configuration identified by UUID. Validates the new configuration before applying changes. Triggers vCenter license discovery job upon successful update.
Retrieves comprehensive information about the HCX Manager''s license activation status, including activation type, grace period information, and communication health with HCX Cloud.
Grace Period:
- New deployments have a grace period before activation is required
- VCF Post-Eval mode includes extended grace periods
- Grace period expiration triggers service restrictions
Communication Health:
- Monitors connectivity between HCX Manager and HCX Cloud
- Warns when communication is degraded
- Critical when communication is broken beyond grace period
Retrieves the configured geographical location of the HCX Manager's datacenter. This location information is used for topology visualization and datacenter mapping in the HCX UI.
Configures the geographical location of the HCX Manager's datacenter. This location is used for topology visualization and will be synchronized with paired HCX sites.
Searches for cities by name to retrieve their geographical coordinates. Supports case-insensitive partial string matching on city names. This API is used to find accurate latitude/longitude values when configuring datacenter location.
Retrieves the current NSX Manager configuration. Passwords are automatically redacted from the response for security.
Creates a new NSX Manager configuration. Validates NSX Manager credentials and connectivity, verifies NSX-vCenter association, and populates cluster manager information for NSX-T. Automatically creates self-site pairing if successful.
Updates an existing NSX Manager configuration identified by UUID. Validates the new configuration before applying changes.
Retrieves the configured HTTP proxy settings for the HCX Manager. HTTP proxy is used by HCX Manager to access external services and internet resources.
Returns:
- Proxy Host: Hostname or IP address of proxy server
- Proxy Port: Port number for proxy connection
- Non-Proxy Hosts: Comma-separated list of hosts to bypass proxy
- Username: Authentication username (if proxy requires auth)
Configures HTTP proxy settings for the HCX Manager appliance. The proxy is used for outbound HTTP/HTTPS connections to external services. For non-proxy hosts, wildcards (*.local, *.example.com) are supported.
Removes the configured HTTP proxy settings from the HCX Manager. After removal, the HCX Manager will connect directly to external services without using a proxy.
Warning: Removing proxy may break connectivity if direct access is not available
Retrieves the configured role mappings for vSphere SSO user groups. Maps vSphere AD/LDAP user groups to HCX roles for access control.
HCX Roles:
Legacy roles automatically converted to their counterparts, and groups must belong to vCenter Single Sign-On integrated Identity Sources.
- System Administrator: (legacy) Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Enterprise Administrator: (legacy) Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Appliance Administrator: (legacy) Allows users to view and modify VCF Operations HCX Management Appliance configurations.
- Migration Admin: Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration User: Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration Appliance Admin: Allows users to view and modify VCF Operations HCX Management Appliance configurations.
User Group Format:
- Fully qualified group names (e.g., vsphere.local\Administrators)
- Domain-Qualified format: domain\groupname
- No commas allowed in group names (stripped automatically)
Updates role mappings for vSphere SSO user groups. Configures which AD/LDAP groups have access to HCX and their privilege levels.
Validations:
- Role name cannot be empty
- At least one role mapping required in request
- User group names cannot be null or empty
- Duplicate groups within same role are removed
Legacy to New Role Name:
- "System Administrator" → "Migration Admin"
- "Enterprise Administrator" → "Migration User"
- "Appliance Administrator" → "Migration Appliance Admin"
HCX Roles:
- System Administrator: (legacy) Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Enterprise Administrator: (legacy) Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Appliance Administrator: (legacy) Allows users to view and modify VCF Operations HCX Management Appliance configurations.
- Migration Admin: Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration User: Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration Appliance Admin: Allows users to view and modify VCF Operations HCX Management Appliance configurations.
User Group Format:
- Domain-Qualified: domain\groupname (e.g., vsphere.local\Administrators)
- Commas automatically stripped
- Case-Sensitive
Important Notes:
- Changes take effect immediately for new logins
- Existing user sessions not affected (re-login required)
- Replacing existing mappings (not additive)
- Empty array removes all role mappings
Searches for user groups from VCF SSO Identity Provider using SCIM 2.0 protocol. Used to discover available AD/LDAP groups for HCX role mapping configuration.
Details:
- Internally queries VCF SSO (vIDB) via SCIM 2.0 Groups API
- Supports pagination (startIndex, itemsPerPage)
- Filter by group name (partial match)
- Returns group ID, display name, and domain
- Maximum 100 results per page (default)
Prerequisites:
- vIDB (VCF SSO) must be configured (/api/admin/global/config/vidb)
- OAuth client credentials must be valid
- HCX Manager must have network connectivity to VCF SSO
Pagination:
- Use startIndex for pagination (1-based index)
- Use count to control page size (max 100)
- Check totalResults to determine if more pages exist
Retrieves the configured role mappings for VCF SSO (vIDB) user groups. Returns which VCF SSO groups are assigned to HCX roles for VCF-managed environments.
VCF SSO vs vSphere SSO:
- vSphere SSO: Traditional AD/LDAP groups (GET /api/admin/global/config/roleMappings)
- VCF SSO (vIDB): VCF-managed identity provider with SCIM API (this endpoint)
- Both VCF SSO and vSphere SSO can coexist
HCX Roles:
- System Administrator: (legacy) Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Enterprise Administrator: (legacy) Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Appliance Administrator: (legacy) Allows users to view and modify VCF Operations HCX Management Appliance configurations.
- Migration Admin: Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration User: Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration Appliance Admin: Allows users to view and modify VCF Operations HCX Management Appliance configurations.
Updates role mappings for VCF SSO (vIDB) user groups. Configures which VCF SSO groups have access to HCX and their privilege levels in VCF-managed environments.
Validations:
- Role name cannot be empty
- User group names cannot be null or empty
- At least one role mapping recommended (but empty array allowed)
VCF SSO vs vSphere SSO:
- vSphere SSO: Traditional AD/LDAP groups (PUT /api/admin/global/config/roleMappings)
- VCF SSO (vIDB): VCF-managed identity provider with OAuth (this endpoint)
- VCF SSO groups should be fetched via SCIM API (searchGroups) before assignment
HCX Roles:
- System Administrator: (legacy) Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Enterprise Administrator: (legacy) Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Appliance Administrator: (legacy) Allows users to view and modify VCF Operations HCX Management Appliance configurations.
- Migration Admin: Allows users to create and modify network profiles, compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration User: Allows users to create and modify compute profiles and service meshes. Also allows users to perform migrations and network extensions.
- Migration Appliance Admin: Allows users to view and modify VCF Operations HCX Management Appliance configurations.
Prerequisites:
- vIDB (VCF SSO) must be configured (/api/admin/global/config/vidb)
- Groups should exist in VCF SSO (verify via searchGroups)
- OAuth client must have appropriate permissions
Important Notes:
- Changes take effect immediately for new VCF SSO logins
- Existing user sessions not affected (re-login required)
- Replaces existing VCF SSO mappings (not additive)
- Empty array clears all VCF SSO role mappings
Retrieves the current HCX Service Proxy configuration. The service proxy is used in air-gapped or restricted network environments (e.g., FedRamp) where the HCX Manager needs to communicate with HCX Cloud services through a designated proxy endpoint.
Configures the HCX Service Proxy endpoint for air-gapped or restricted network environments. This proxy endpoint enables communication between the HCX Manager and HCX Cloud services.
Updates an existing HCX Service Proxy configuration identified by UUID. Use this to change the proxy endpoint URL or update configuration parameters.
Generates a new active session token for authentication. Supports both local PAM authentication and vSphere SSO authentication. Returns session details including user role information along with an authentication token in the response header.
Retrieves comprehensive information about the active session including user details, roles, cloud environment, and organization memberships. Requires valid authentication token in header.
Deletes the current active session, effectively logging out the user. Invalidates the authentication token.
Retrieves the current Lookup Service (vCenter Server SSO) configuration for vSphere local user authentication
Add Lookup Service (vCenter Server SSO) for vSphere local user authentication for both Administrator and Operations portal
Updates an existing Lookup Service configuration identified by UUID. Validates the new configuration before applying changes.
Retrieves the NSP configuration, which defines the public access URL and cloud type for HCX deployments.
Returns:
- baseProxyUrl: Public URL for accessing HCX through cloud provider's proxy/gateway
- cloudType: Type of cloud platform (e.g., "VC", "VCD")
- isVcdGatewaysEnabled: Whether VCD gateways are enabled
- isDefault: Whether this is the default NSP configuration
- extensibilityExchange: Extensibility exchange configuration
- UUID: Unique identifier for the NSP configuration
Configures the NSP config for Cloud HCX deployments. This sets the public access URL and cloud type for accessing HCX through cloud provider infrastructure.
Configuration Parameters:
- baseProxyUrl: Required, public URL for HCX access (e.g., https://hcx-proxy.vmc.vmware.com)
- cloudType: Required, cloud platform type ("VC", "VCD")
- isDefault: Optional, whether this is the default NSP configuration (boolean)
Updates an existing NSP configuration. Modifies the public access URL
Updatable Parameters:
- baseProxyUrl: Public URL for HCX access
- cloudType: Cloud platform type (cannot change type after initial setup)
- isVcdGatewaysEnabled: VCD gateways enablement flag
Important Notes:
- Changing baseProxyUrl may break connectivity temporarily
- Ensure new URL is accessible before applying
- May require HCX services restart for changes to take effect
Retrieves the list of configured static routes on the HCX Manager appliance. These static routes are used to direct network traffic to specific destinations through custom gateways.
Adds a new static route to the HCX Manager appliance. Static routes allow you to define custom network paths for specific destination networks.
Validations:
- static_network: Must be a valid IPv4 address (e.g., 192.168.0.0)
- static_prefix: Integer between 0 and 32 (CIDR prefix length)
- static_gateway_ip: Must be a valid IPv4 address and should be reachable
Important Notes:
- Duplicate routes (same network/prefix) may override existing routes
- Gateway must be reachable from HCX Manager's network
- Invalid gateway can cause connectivity issues
- Routes are applied to the primary network interface
Retrieves comprehensive network configuration for the HCX Manager appliance, including hostname, domain, IPv4 addresses, DNS settings, and HTTP proxy configuration.
Returns:
- Hostname & Domain: System identification details
- IPv4 Configuration: Interface, IP address, netmask, gateway
- DNS Settings: IPv4/IPv6 DNS servers and search domain list
- Proxy Settings: HTTP proxy server, port, credentials (if configured)
Configures DNS server addresses and search domains for the HCX Manager appliance.
Important Notes:
- Service Restart Required: You must restart the Application Service and Web Service for DNS changes to take effect
- Changes are persistent across reboots
- Maximum 3 DNS servers recommended (OS limitation)
- DNS search domains help resolve unqualified hostnames
Restart Commands:
systemctl restart app-engine
systemctl restart web-engine
Warning: Without DNS configuration, the HCX Manager may not resolve:
- vCenter Server hostnames
- NSX Manager hostnames
- NTP server hostnames
- External service endpoints
Removes all DNS server configuration from the HCX Manager appliance. Resets DNS settings to defaults or empty.
Important Notes:
- Service Restart Required: You must restart the Application Service and Web Service after removing DNS
- Use with caution: Removing DNS may break connectivity to vCenter, NSX, and other services
- Consider reconfiguring DNS immediately after removal
Restart Commands:
systemctl restart app-engine
systemctl restart web-engine
Warning: Without DNS configuration, the HCX Manager may not resolve:
- vCenter Server hostnames
- NSX Manager hostnames
- NTP server hostnames
- External service endpoints
Retrieves current time settings for the HCX Manager appliance including NTP servers, current date/time, and timezone configuration.
Configures time settings for the HCX Manager appliance. Supports NTP server configuration, manual time setting, and timezone selection.
Validations:
- NTP server must be valid hostname or IP address
- Timezone must be valid (e.g., America/Los_Angeles, UTC, Europe/London)
- Datetime format: MMM dd yyyy HH:mm:ss (e.g., Nov 14 2025 10:30:00)
- Cannot set manual datetime when NTP is configured
Important Notes:
- Services restart may be required: Component services may need restart for NTP changes to take effect
- NTP servers can be hostnames or IP addresses
- Timezone changes take effect immediately
- Incorrect time can cause certificate validation failures
Removes NTP server configuration from the HCX Manager appliance. After removal, time will not be automatically synchronized and may drift.
Important Notes:
- Service restart may be required: Component services may need restart after removing NTP
- Time drift may occur after NTP removal
- Consider setting manual time or reconfiguring NTP after removal
- System clocks will drift over time without NTP
Changes the password for HCX Manager appliance users (admin or root). Validates the old password via PAM authentication, enforces password policy, and invalidates the current session token after successful change.
Password Policy(Non VCF Managed):
- Minimum length: 15 characters
- Maximum length: 20 characters
- Must contain: lowercase letter, uppercase letter, number, special character (! @ # $ ^ *)
- Must NOT contain: dictionary words, palindromes, >4 monotonic sequences, 3 consecutive identical characters
- Regex pattern:
^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$^*])(?=\\S+$).{15,20}$
Password Policy(VCF Managed):
- HCX Manager Appliance user password is managed from VCF Operations
- VCF Operations centrally manage the password policies for all managed components
- Hence, password policy validation is skipped at HCX
Retrieves the Apache reverse proxy configuration for Cloud HCX Manager. This configuration defines how Apache HTTP Server proxies requests to backend services for public internet access.
Configures Apache reverse proxy rules for Cloud HCX Manager. This sets up URI-to-backend forwarding rules for public internet access through cloud provider infrastructure.
Retrieves the list of HCX deployed dataplance appliances in the infrastructure. This API returns information about Interconnect (IX), Network Extension (NE), and WAN Optimization (WANOPT) appliances that can be included in tech support log collection.
Fleet Appliance Types:
- GATEWAY (Interconnect/IX): Gateway appliances for site-to-site connectivity
- L2C_HT (Network Extension): Layer 2 network extension appliances
- WANOPT: WAN optimization appliances
Retrieves the list of HCX Sentinel VMs deployed in the infrastructure. Sentinels are lightweight monitoring VMs used for health checks and connectivity testing between sites.
Initiates an asynchronous tech support log collection job. Collects logs from HCX Manager, fleet appliances (IX, NE, WANOPT), and Sentinel VMs. Returns a job ID for tracking progress.
Collection Scope:
- HCX Manager: Always included (web engine, app engine, HTTPD, database logs)
- Fleet Appliances: Specify appliance IDs in
fleetAppliancesarray - Sentinels: Specify Sentinel IDs in
sentinelsarray - Database: Full PostgreSQL dump (if
collectDbDumpis true)
Async Operation:
- Job runs in background (may take several minutes)
- Use
/jobStatus/{jobId}to check progress - Download bundle when job state is SUCCESS
Retrieves the current status of a tech support log collection job. Polls this endpoint to monitor progress and determine when the bundle is ready for download.
Job States:
- RUNNING: Job is in progress
- SUCCESS: Job completed successfully, bundle ready for download
- FAILED: Job failed completely
- PARTIAL_SUCCESS: Job completed with some component failures (fleet or Sentinels)
Downloads the generated tech support log bundle as a compressed archive (.tar.gz). The bundle contains logs from HCX Manager and optionally from fleet appliances, Sentinels, and database dumps.
Retrieves the current vCenter configuration. Passwords are automatically redacted from the response for security.
Creates a new vCenter configuration. Validates the vCenter credentials and connectivity before saving. Automatically triggers license discovery job and creates self-site pairing if successful.
Updates an existing vCenter configuration identified by UUID. Validates the new configuration before applying changes. Triggers license discovery job upon successful update.
Retrieves the current VMware Cloud Director (VCD) configuration. Passwords are automatically redacted from the response for security.
Add new VMware Cloud Director (VCD) configuration. Validates VCD connectivity, retrieves and populates VCD components (public URL, AMQP details). Automatically enriches configuration with systemExchange, systemPrefix, and UI EndPoint from VCD.
Updates an existing VMware Cloud Director (VCD) configuration identified by UUID. Validates the new configuration before applying changes.
Retrieves the current RabbitMQ (RMQ) configuration for VCD deployments. Passwords are automatically redacted from the response for security. This is a single-item configuration.
Add new RabbitMQ (RMQ) configuration for VCD deployments. Tests RMQ connectivity with and without trust-all certificates. If connection succeeds only with trust-all, returns a warning to import RMQ certificate manually. This is a single-item configuration (only one RMQ can be configured).
Updates an existing RabbitMQ (RMQ) configuration identified by UUID. Validates connectivity before applying changes.
Retrieves the current vCenter Identity Broker (vIDB/VCF SSO) configuration for OAuth authentication. Client secret is automatically redacted from the response for security.
Creates a new vCenter Identity Broker (vIDB/VCF SSO) configuration for OAuth-based authentication. Validates vIDB connection, retrieves and updates OAuth App details with redirect URLs and TTLs. If certificate is provided, imports it into trust store.
Updates an existing vCenter Identity Broker (vIDB/VCF SSO) configuration identified by UUID. Validates vIDB connection before applying changes. If certificate is provided, imports it into trust store.