VCenter Connections Save
Persists a tested and verified vCenter connection with authoritative instance UUID and certificate trust material. Requires the ADMIN role.
The verified connection to save: displayName, host, port, username, password and the verifiedConnectionToken that the connection test issued, with the optional autoEnrollmentEnabled flag.
Show optional properties
{
"displayName": "string",
"host": "string",
"port": 0,
"username": "string",
"password": "string",
"verifiedConnectionToken": "string"
}
{
"displayName": "Primary vCenter",
"host": "vcenter.example.com",
"port": 443,
"username": "svcvtp.example",
"password": "<redacted>",
"verifiedConnectionToken": "<redacted>",
"autoEnrollmentEnabled": false
}
Human-readable display name for the vCenter connection
vCenter host address
vCenter HTTPS port
vCenter username
vCenter password
Server-issued single-use verified connection token
Optional. Enables auto-enrollment for the saved connection; an omitted value is treated as false
201 Created successful response envelope. The registered connection, which never carries the password
{
"id": "1",
"displayName": "Primary vCenter",
"host": "vcenter.example.com",
"port": 443,
"username": "svcvtp.example",
"enabled": true,
"vcenterInstanceUuid": "00000000-0000-4000-8000-000000000021",
"trustProvenance": "USER_APPROVED",
"certSha256": "01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF",
"certSubject": "CN=vcenter.example.com,O=Example Org",
"certNotAfter": "2026-03-31T00:00:00Z",
"lastConnectionStatus": "CONNECTING",
"lastConnectionSecurityCode": "NONE",
"createdAt": "2026-01-15T09:20:00Z",
"discoveredHostCount": null,
"discoveredHostCountStatus": null,
"lastVerifiedSyncAt": null,
"inventoryHoldReason": null,
"inventoryHoldObservedHosts": null,
"inventoryHoldCurrentHosts": null,
"inventoryHoldId": null,
"inventoryHoldExcludedProductHosts": null,
"removalProgress": null
}
Unique database identifier for the connection
Operator-chosen name of the connection, trimmed of surrounding spaces when the connection is added; unique ignoring case
Host address
HTTPS port
Account the Console signs in to vCenter with, trimmed of surrounding spaces when the connection is added; the password is never returned
Whether discovery is currently enabled for this connection
Authoritative vCenter instance UUID
Provenance of trust for the active vCenter certificate
CA_SAN_VERIFIED: The certificate passed strict CA and subject alternative name validation; also the value when none is givenUSER_APPROVED: An administrator approved the certificate through a trust challenge, and the connection is pinned to it
SHA-256 fingerprint of the trusted leaf certificate
Subject of the trusted leaf certificate
Expiration timestamp of the trusted leaf certificate
Operational lifecycle state of a vCenter discovery connection. The server code also declares WAITING_FOR_AGENTS (the code found no place that sets it); it is not in the enum list
DISCONNECTED: Not connected: the state after STOPPING, and the state reported when none is storedCONNECTING: The initial state of a newly added connection, and the state of each connect attemptBASELINING: The connection is made and the security code is cleared; the inventory baseline is being loadedWATCHING: The baseline is loaded and the worker follows inventory changesDEGRADED_RETRYING: A transient transport failure occurred (security code CONNECTIVITY_FAILURE); the worker retriesREBUILDING: The session or its change lineage was invalidated; the worker reconnects through CONNECTING and BASELININGSTOPPING: Shutdown is in progress; DISCONNECTED followsOPERATOR_ACTION_REQUIRED: The worker stopped retrying until an operator acts; the security code names the reason (trust required, pinned certificate expired, identity mismatch, authentication failure or insufficient privilege)REMOVING: Removal was requested; discovery is fenced and the Agents of the connection's hosts are being offboarded, so the connection is not removed yetATTENTION_REQUIRED: A removal pass finished with at least one host that could not be offboarded; the connection is kept so the operator can retry or force the removalREMOVED: Every host has an outcome and the connection row was deleted; returned by the removal call only
Security or error reason code for an operator-action or degraded vCenter connection
NONE: No security or error condition; the value stored when a connection is added and whenever the worker reaches CONNECTING or BASELINING cleanlyTLS_TRUST_REQUIRED: Certificate verification failed on connect, or the pinned certificate is not yet valid (set with OPERATOR_ACTION_REQUIRED)VCENTER_IDENTITY_MISMATCH: The live vCenter instance UUID differs from the one recorded for the connection (set with OPERATOR_ACTION_REQUIRED)PINNED_CERTIFICATE_EXPIRED: The pinned certificate has expired and the expired-pin policy does not allow continuing (set with OPERATOR_ACTION_REQUIRED)AUTHENTICATION_FAILURE: The vCenter rejected the stored credentials (set with OPERATOR_ACTION_REQUIRED)INSUFFICIENT_PRIVILEGE: The account lacks the privilege to enumerate the inventory (set with OPERATOR_ACTION_REQUIRED)CONNECTIVITY_FAILURE: The vCenter could not be reached or a transient transport failure occurred (set with DEGRADED_RETRYING)
Creation timestamp
Number of ACTIVE vCenter-managed hypervisor rows stored for this connection, the same rows Hypervisors, Discover lists by default; STALE and standalone rows are excluded. Read from the stored inventory, never from vCenter. Present on the list response only
Present on the list response only; null elsewhere
Time of the last successful baseline or WaitForUpdatesEx reply of the running discovery worker, null until the first one after a Console start. Not stored. Present on the list response only
Why removal of hosts missing from a complete vCenter snapshot is held: EMPTY_SNAPSHOT (no hosts although some are known) or MASS_REDUCTION (at least the configured number of hosts, and more than the configured percentage, would leave); null when no removal is held. Present on the list response only
Hosts the held snapshot listed; null without a hold. Present on the list response only
Hosts currently known for the connection when the removal was held; null without a hold. Present on the list response only
Identifier of the current hold, new for every hold; the confirmation must echo it so a confirmation made for one hold cannot apply to a later one. Null without a hold. Present on the list response only
How many of the hosts whose removal is held are identified as unsupported mobility agent hosts, already hidden from Discover pending removal; 0 or null without a hold. Present on the list response only
Progress of Agent unenrollment while the connection is REMOVING, and the last pass's counts while it is ATTENTION_REQUIRED after a failed removal; null otherwise, and after a Console restart
400 Bad Request: MISSING_FIELD when displayName, host, username, password or verifiedConnectionToken is missing or blank; INVALID_PORT when port is outside 1 to 65535; INVALID_VERIFIED_TOKEN when the verification token is unknown, already used or expired; TOKEN_BINDING_MISMATCH when the host, port, username or password differs from the tested connection; MISSING_INSTANCE_UUID when the token carries no vCenter instance UUID; INVALID_TRUST_PROVENANCE when the token carries no trust provenance; MALFORMED_REQUEST when the body cannot be read
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
409 Conflict: DUPLICATE_DISPLAY_NAME when the display name is already used, compared without regard to case; DUPLICATE_VCENTER_INSTANCE when a connection for the same vCenter instance UUID is already registered; DUPLICATE_ROUTING_ENDPOINT when a connection for the same host and port is already registered; MAX_CONCURRENT_VCENTERS_EXCEEDED when the maximum number of concurrent discovery workers is reached
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"displayName":"string","host":"string","port":"integer","username":"string","password":"string","verifiedConnectionToken":"string"}' https://{api_host}/api/v1/vcenter-connections