VCenter Connections Accept Trust Challenge

VCenter Connections Accept Trust Challenge
Accept an inspected leaf certificate and verify credentials via exact pinning

Consumes a single-use trustChallengeId, establishes EXACT_PIN connection, verifies credentials, and mints verifiedConnectionToken. Requires the ADMIN role.

Request
URI
POST
https://{api_host}/api/v1/vcenter-connections/accept-trust-challenge
COPY
Request Body

The trust challenge to accept and the endpoint it was issued for: trustChallengeId, host, port, username and password.

AcceptTrustChallengeRequest of type(s) application/json
Required  

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>"
}
string
trustChallengeId
Required  

Server-owned opaque inspection challenge identifier

string
host
Required  

vCenter host address matching the challenge

integer As int32 As int32
port
Required  

vCenter HTTPS port matching the challenge

string
username
Required  

vCenter username

string
password
Required  

vCenter password

Authentication
This operation uses the following authentication methods.
Responses
200

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

Returns TestVCenterConnectionResult of type(s) application/json
{
    "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>"
}
string
status
Required  

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 returned
  • TLS_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 returned
  • CONNECTIVITY_FAILURE: The vCenter host and port could not be reached
  • TLS_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 inspected
  • AUTHENTICATION_FAILURE: The vCenter rejected the user name or password
  • INSUFFICIENT_PRIVILEGE: The sign-in worked, but the account lacks the privilege to enumerate the vCenter inventory
  • VCENTER_IDENTITY_MISMATCH: No behaviour is documented for this value. No producing site in the current server code
  • PINNED_CERTIFICATE_EXPIRED: No behaviour is documented for this value. No producing site in the current server code
  • UNKNOWN_FAILURE: Any other failure of the probe; the message carries the cause
Enumeration: SUCCESS, TLS_TRUST_REQUIRED, CONNECTIVITY_FAILURE, TLS_FAILURE, AUTHENTICATION_FAILURE, INSUFFICIENT_PRIVILEGE, VCENTER_IDENTITY_MISMATCH, PINNED_CERTIFICATE_EXPIRED, UNKNOWN_FAILURE
string
message
Required  

User-facing diagnostic or error message (contains no credentials)

string
vcenterVersion
Optional

Detected vCenter product version if available

string
apiVersion
Optional

Detected vCenter API version if available

string
instanceUuid
Optional

Authoritative vCenter instance UUID if successfully authenticated

string
trustChallengeId
Optional

Single-use server-issued inspection challenge ID when status is TLS_TRUST_REQUIRED

string
tlsFailureReason
Optional

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 trusted
  • HOSTNAME_MISMATCH: The issuer is trusted, but the certificate does not match the host name used
  • UNTRUSTED_CA_AND_HOSTNAME_MISMATCH: The issuer is not trusted and the certificate does not match the host name used
  • CERTIFICATE_EXPIRED: The certificate end date has passed; no trust challenge is created for it
  • CERTIFICATE_NOT_YET_VALID: The certificate start date is in the future; no trust challenge is created for it
  • TLS_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
Enumeration: UNTRUSTED_CA, HOSTNAME_MISMATCH, UNTRUSTED_CA_AND_HOSTNAME_MISMATCH, CERTIFICATE_EXPIRED, CERTIFICATE_NOT_YET_VALID, TLS_HANDSHAKE_FAILURE
object
certificate
Optional

Presented X.509 certificate presentation and health details

string
verifiedConnectionToken
Optional

Single-use server-issued verification token required for Save


400

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

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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)

Returns ForbiddenWrite of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    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