VCenter Connections Accept Trust Challenge
Consumes a single-use trustChallengeId, establishes EXACT_PIN connection, verifies credentials, and mints verifiedConnectionToken. Requires the ADMIN role.
The trust challenge to accept and the endpoint it was issued for: trustChallengeId, host, port, username and password.
Show optional properties
{
"trustChallengeId": "string",
"host": "string",
"port": 0,
"username": "string",
"password": "string"
}
{
"trustChallengeId": "00000000-0000-4000-8000-000000000041",
"host": "vcenter.example.com",
"port": 443,
"username": "svcvtp.example",
"password": "<redacted>"
}
Server-owned opaque inspection challenge identifier
vCenter host address matching the challenge
vCenter HTTPS port matching the challenge
vCenter username
vCenter password
200 OK successful response envelope. The probe result of the exact-pin connection; on success it carries the vCenter version, the instance UUID, the accepted certificate and the verifiedConnectionToken that saving the connection needs
{
"status": "SUCCESS",
"message": "Certificate trust accepted and connection verified successfully.",
"vcenterVersion": "8.0.2",
"apiVersion": "8.0.2.0",
"instanceUuid": "00000000-0000-4000-8000-000000000021",
"trustChallengeId": null,
"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": "<redacted>"
}
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 trustChallengeId, host, username or password is missing or blank; INVALID_PORT when port is outside 1 to 65535; INVALID_TRUST_CHALLENGE when the challenge is unknown, already used or expired; CHALLENGE_ENDPOINT_MISMATCH when the host or port differs from the challenge; 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 '{"trustChallengeId":"string","host":"string","port":"integer","username":"string","password":"string"}' https://{api_host}/api/v1/vcenter-connections/accept-trust-challenge