VCenter Connections Retrust Certificate
Replaces the pinned certificate after the administrator echoes the fingerprints of the old and the new certificate, re-enters the vCenter password and confirms. The new certificate is pinned exactly and the same vCenter instance UUID must answer before anything is stored; trust is replaced atomically, both fingerprints are audited, the source restarts with the new trust and, if it cannot restart, the previous trust is restored. A challenge is single-use and bound to the connection's endpoint. Requires the ADMIN role.
vCenter connection id
1
The challenge to approve, both fingerprints, the vCenter password and the explicit confirmation.
Show optional properties
{
"trustChallengeId": "string",
"expectedOldCertSha256": "string",
"expectedNewCertSha256": "string",
"password": "string",
"confirmReplacement": false
}
{
"trustChallengeId": "00000000-0000-4000-8000-000000000042",
"expectedOldCertSha256": "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",
"expectedNewCertSha256": "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00",
"password": "<redacted>",
"confirmReplacement": true
}
Single-use identifier returned by the trust challenge of this connection
Fingerprint of the certificate being replaced
Fingerprint of the new certificate, as shown in the challenge
The vCenter password, re-entered to verify the new endpoint
Must be true
200 OK successful response envelope. The connection with the new certificate details.
{
"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": "WATCHING",
"lastConnectionSecurityCode": "NONE",
"createdAt": "2026-01-15T09:20:00Z",
"autoEnrollmentEnabled": true,
"discoveredHostCount": null,
"discoveredHostCountStatus": null,
"lastVerifiedSyncAt": null,
"inventoryHoldReason": null,
"inventoryHoldObservedHosts": null,
"inventoryHoldCurrentHosts": null,
"inventoryHoldId": null,
"inventoryHoldExcludedProductHosts": null,
"removalProgress": null
}
Database identifier of the connection, as a decimal string
Operator-chosen name of the connection, trimmed when the connection is added; unique ignoring case
vCenter host name or address, trimmed when the connection is added
HTTPS port of the vCenter; 443 when none was supplied when the connection was added
Account the Console signs in to vCenter with; the password is never returned
Whether discovery runs for the connection; set when the connection is added and cleared when removal starts
Instance UUID of the vCenter, taken from the verification token when the connection was added and compared with the live vCenter on every connect; null when not recorded
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 vCenter certificate; null when no certificate is recorded
Subject of the trusted vCenter certificate; null when no certificate is recorded
End of validity of the trusted vCenter certificate, ISO 8601 date-time with offset; null when no certificate is recorded or its end date could not be parsed
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)
Time the connection was added, ISO 8601 date-time with offset
Whether Auto Enrollment is switched on for the connection; false when no setting is stored
Always null here; the count is returned by the list operation 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: MALFORMED_REQUEST, MISSING_FIELD, CONFIRMATION_REQUIRED, CHALLENGE_ENDPOINT_MISMATCH or VERIFICATION_FAILED
{
"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 or CSRF_ERROR. ADMIN role required.
{
"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.
404 Not Found: CONNECTION_NOT_FOUND
"ApiErrorResponse Object"
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: SOURCE_REMOVING, CERTIFICATE_CHANGED, FINGERPRINT_CONFIRMATION_MISMATCH, NEW_CERTIFICATE_EXPIRED, NO_CERTIFICATE_CHANGE, VCENTER_IDENTITY_MISMATCH, CONNECTION_CHANGED or ACTIVATION_FAILED_ROLLED_BACK
"ApiErrorResponse Object"
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 PUT -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"trustChallengeId":"string","expectedOldCertSha256":"string","expectedNewCertSha256":"string","password":"string","confirmReplacement":"boolean"}' https://{api_host}/api/v1/vcenter-connections/{id}/trusted-certificate