VCenter Connections Test Connection
Diagnostic probe testing strict TLS trust, credential validity, and instance UUID. Requires the ADMIN role.
The vCenter endpoint to probe: host, port, username and password. Nothing is stored.
Show optional properties
{
"host": "string",
"port": 0,
"username": "string",
"password": "string"
}
{
"host": "vcenter.example.com",
"port": 443,
"username": "svcvtp.example",
"password": "<redacted>"
}
vCenter host address (FQDN or IPv4/IPv6)
vCenter HTTPS port
vCenter username
vCenter password
200 OK successful response envelope. The probe result with its status and message; on success it carries the vCenter version, the instance UUID and the verifiedConnectionToken that saving the connection needs
{
"status": "TLS_TRUST_REQUIRED",
"message": "TLS/certificate verification required: UNTRUSTED_CA. Review the certificate details and explicitly accept trust if valid.",
"vcenterVersion": null,
"apiVersion": null,
"instanceUuid": null,
"trustChallengeId": "00000000-0000-4000-8000-000000000041",
"tlsFailureReason": "UNTRUSTED_CA",
"certificate": {
"subject": "CN=vcenter.example.com,O=Example Org",
"issuer": "CN=vcenter.example.com,O=Example Org",
"validFrom": "2026-01-01T00:00:00Z",
"validTo": "2026-03-31T00:00:00Z",
"sha256Fingerprint": "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",
"isExpired": false,
"subjectAlternativeNames": [
"vcenter.example.com"
]
},
"verifiedConnectionToken": null
}
Status of a vCenter diagnostic test or trust evaluation
SUCCESS: The probe signed in and read the vCenter version, API version and instance UUID; a verified connection token is returnedTLS_TRUST_REQUIRED: Strict certificate validation failed with a condition an administrator can approve (untrusted CA, host name mismatch, or both); a trust challenge, the failure reason and the certificate details are returnedCONNECTIVITY_FAILURE: The vCenter host and port could not be reachedTLS_FAILURE: The certificate is expired, not yet valid or failed the handshake for another reason, which administrator trust cannot bypass, or the server certificate could not be inspectedAUTHENTICATION_FAILURE: The vCenter rejected the user name or passwordINSUFFICIENT_PRIVILEGE: The sign-in worked, but the account lacks the privilege to enumerate the vCenter inventoryVCENTER_IDENTITY_MISMATCH: No behaviour is documented for this value. No producing site in the current server codePINNED_CERTIFICATE_EXPIRED: No behaviour is documented for this value. No producing site in the current server codeUNKNOWN_FAILURE: Any other failure of the probe; the message carries the cause
User-facing diagnostic or error message (contains no credentials)
Detected vCenter product version if available
Detected vCenter API version if available
Authoritative vCenter instance UUID if successfully authenticated
Single-use server-issued inspection challenge ID when status is TLS_TRUST_REQUIRED
Specific cryptographic reason for TLS handshake or trust verification failure
UNTRUSTED_CA: The certificate is within its validity period and matches the host, but its issuer is not trustedHOSTNAME_MISMATCH: The issuer is trusted, but the certificate does not match the host name usedUNTRUSTED_CA_AND_HOSTNAME_MISMATCH: The issuer is not trusted and the certificate does not match the host name usedCERTIFICATE_EXPIRED: The certificate end date has passed; no trust challenge is created for itCERTIFICATE_NOT_YET_VALID: The certificate start date is in the future; no trust challenge is created for itTLS_HANDSHAKE_FAILURE: The certificate is within its validity period, trusted and matches the host, yet the secure connection failed; no trust challenge is created for it
Presented X.509 certificate presentation and health details
Single-use server-issued verification token required for Save
400 Bad Request: MISSING_FIELD when host, username or password is missing or blank; INVALID_PORT when port is outside 1 to 65535; 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.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"host":"string","port":"integer","username":"string","password":"string"}' https://{api_host}/api/v1/vcenter-connections/test-connection