My HealtheVet (MHV)

Last Updated: December 17, 2024

This page will give you a better understanding of the My HealtheVet (MHV) Application Program Interfaces (API) by covering everything from integration points and trust chains to monitoring and incident response.

Overview of My HealtheVet

MHV APIs provide Secure Messaging (SM), Prescriptions (RX), View Test and Lab Results, and Health Records (aka Blue Button [BB]) support as well as authentication. MHV is also a credential service provider (CSP).

The integration with MHV is provided via NSOC configured tunnels to the MHV HA systems in Terremark within the VA network. MHV provides a single API gateway for all services; it acts as a façade in front of two independent services for (RX + BB) and (SM), so it’s possible for one or the other of the backing services to be down while the other is up.

Network connectivity and L7 status checks reported by the External Service Status dashboard (SOCKS proxy access is required).

MHV will be available as a sign-in option for VA.gov applications until January 31, 2025.

Integration points

Prescriptions (RX)

Type: REST
Endpoint: #{ENV['MHV_HOST']}/mhv-api/patient/v1/

Error Indicator:

StatsD: api.external_http_request.Rx
Datadog:

CODE

vets_api.statsd.api_external_http_request_Rx_success
vets_api.statsd.api_external_http_request_Rx_failed
vets_api.statsd.api_external_http_request_Rx_skipped

Secure messaging (SM)

Type: REST
Endpoint: #{ENV['MHV_SM_HOST']}/mhv-sm-api/patient/v1/

Error Indicator:

StatsD: api.external_http_request.SM
Datadog:

CODE

vets_api.statsd.api_external_http_request_SM_success
vets_api.statsd.api_external_http_request_SM_failed
vets_api.statsd.api_external_http_request_SM_skipped

Authentication

We don't connect directly to MHV for authentication. Instead, we redirect to ID.me who redirects to MHV and redirects back to ID.me who redirects back to VA.gov. More details on the login flow are in the vets.gov-team repository.

Trust chains

The essapi-sysb.myhealth.va.gov is a SAN for our internal-sysb.myhealth.va.gov certificate. Its certificate chain uses the VA-Internal-S2-ICA11 as the intermediate and the VA-Interal-S2-RCA2 as the root. The ICA and RCA are the same for the production essapi.myhealth.va.gov SAN.

essapi-sysb.myhealth.va.gov (login required)

CODE

   0 s:/DC=gov/DC=va/OU=devices/CN=essapi-sysb.myhealth.va.gov
     i:/DC=gov/DC=va/OU=Services/OU=PKI/CN=Veterans Affairs Device CA B2
   1 s:/DC=gov/DC=va/OU=Services/OU=PKI/CN=Veterans Affairs Device CA B2
     i:/C=US/O=Betrusted US Inc/OU=SSP/OU=Betrusted Production SSP CA A1/CN=Betrusted Production SSP CA A1
   2 s:/C=US/O=Betrusted US Inc/OU=SSP/OU=Betrusted Production SSP CA A1/CN=Betrusted Production SSP CA A1
     i:/C=US/O=U.S. Government/OU=FPKI/CN=Federal Common Policy CA

essapi.myhealth.va.gov (login required)

CODE

   0 s:/DC=gov/DC=va/OU=devices/CN=essapi.myhealth.va.gov
     i:/DC=gov/DC=va/OU=Services/OU=PKI/CN=Veterans Affairs Device CA B2
   1 s:/DC=gov/DC=va/OU=Services/OU=PKI/CN=Veterans Affairs Device CA B2
     i:/C=US/O=Betrusted US Inc/OU=SSP/OU=Betrusted Production SSP CA A1/CN=Betrusted Production SSP CA A1
   2 s:/C=US/O=Betrusted US Inc/OU=SSP/OU=Betrusted Production SSP CA A1/CN=Betrusted Production SSP CA A1
     i:/C=US/O=U.S. Government/OU=FPKI/CN=Federal Common Policy CA
   3 s:/C=US/O=U.S. Government/OU=FPKI/CN=Federal Common Policy CA
     i:/C=US/O=U.S. Government/OU=FPKI/CN=Federal Common Policy CA

Required configuration

The following environment variables must be set in vsp-infra-application-manifests to establish connectivity:

MHV_HOST
MHV_APP_TOKEN
MHV_SM_HOST
MHV_SM_APP_TOKEN

As mentioned above, there is now a single API gateway so MHV_HOST and MHV_SM_HOST should match (and eventually these may be collapsed into one variable). However, the backing services use their own authentication tokens so MHV_APP_TOKEN and MHV_SM_APP_TOKEN are not expected to match. These values live in Parameter Store.

Additionally, custom certificates must be added to the cert chain to allow SSL connectivity, these certificates are placed in /etc/pki/ca-trust/source/anchors/

intb.pem
prod.pem

Monitoring

The Datadog dashboard is available to monitor MHV performance for authentication (requires Datadog access).

Outage status and maintenance windows

Alerts for all planned and unplanned outages of VA online services and systems are sent to ANR (login required).
A release schedule is emailed out with release dates.
Notifications are sent out about outages to the MHV ListServ (login required).

Service level agreement

The Identity Platform team communicates CSP-related service interruptions to VA.gov application teams as promptly as possible. Additionally, the VA.gov status page lists all systems’ operational statuses, including those of CSPs.

Key Contacts

Reach out in the #mhv-medications-rx or #identity-support Slack channels.

Incident Response

Any time PagerDuty has a status other than "active" for MHV a downtime banner is in place on the sign in modal. Vets-api gets the status from PagerDuty once a minute.

If you see an alert for ID.me authentication at the same time as a MHV alert, focus on ID.me as MHV authentication depends on ID.me.
Contact the NSD (1-855-673-4357) to file a ticket for MHV outages. Phone tree 5 (Other issues) -> 1 (VHA). You will be forwarded to a technician.
Send an email describing the issue in detail, including the NSD ticket #, to

CODE

 "Graham, Kenneth J. (BYLIGHT)" <Kenneth.Graham2@va.gov>, "Hormby, Thomas W.
(SMS)" <Thomas.Hormby@va.gov>, "Copeman, Richard L.. (SMS)"
<Richard.Copeman@va.gov>, "Zallar, Kerry (KGS)" <Kerry.Zallar@va.gov>, "Kirk,
Gregory" <Gregory.Kirk@va.gov>, "Phelps, Carl J." <Carl.Phelps@va.gov>, "Good,
Sean M." <Sean.Good@va.gov>, "Robertson, Raquel D.(BYLIGHT)"
<Raquel.Robertson@va.gov>, "Bain, Matthew" <Matthew.Bain@va.gov>, "Moy, Jacob T.
(By Light)" <Jacob.Moy@va.gov>, "Born, Michael A. (Vidoon, Inc)"
<Michael.Born@va.gov>, "Brekke, John L." <John.Brekke@va.gov>.

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.