Skip to content

API Certificate & TLS

1. Overview

The TLS certificate for api.nps.today is renewed on a recurring basis approximately every 6 months. This is not a new practice — it is, and has always been, a routine part of maintaining a secure and compliant API. Most clients are completely unaffected because they trust the underlying Certificate Authority (CA) chain rather than a specific certificate.

However, certain client-side environments — specifically Java-based applications with static or locked-down truststores, or applications that use certificate pinning — may lose connectivity after a renewal if they are not configured to handle routine certificate rotation.

Note: No advance notification is sent before certificate renewals. We recommend ensuring your integration is resilient to routine certificate rotation by following the guidance below.

Certificate Identification

  • Subject Name: api.nps.today
  • Issuer (Intermediate): GeoTrust TLS RSA CA G1
  • Root Authority: DigiCert Global Root G2

2. Understanding the "Java Truststore" Issue

Java applications do not use the standard Windows or macOS system certificate stores. Instead, they rely on a private internal file called the Truststore (typically a file named cacerts).

Why the connection failed:

If your Java application threw one of the following errors after a certificate renewal:

  • javax.net.ssl.SSLHandshakeException
  • PKIX path building failed
  • com.ibm.jsse2.util.h: No trusted certificate found (IBM J9/WebSphere environments)

it is due to one of the following:

  1. Outdated JRE/JDK: Very old Java 8 builds (prior to update 141) do not have the DigiCert Global Root G2 pre-installed in their cacerts file. Environments with a custom or locked-down truststore may also be missing it regardless of Java version.
  2. Explicit Pinning: If your application was configured to trust only the previous specific certificate thumbprint (certificate pinning), it will reject the new certificate even if it is technically valid.
  3. Static Truststores: In many enterprise environments, the cacerts file is locked down. When we rotate our certificate, Java refuses the connection because it cannot verify the "Chain of Trust" up to a known Root CA.

3. Resolution for Java Requesters

To resolve the connection issue, the DigiCert Global Root G2 must be imported into your Java environment.

Step 1: Locate your Truststore

The truststore location depends on your Java runtime:

Standard Oracle / OpenJDK: * Windows: %JAVA_HOME%\lib\security\cacerts * Linux/Unix: $JAVA_HOME/lib/security/cacerts

IBM JVM (WebSphere, Liberty, IBM Semeru): IBM JVMs maintain a separate truststore that is independent of the standard cacerts file. Even if DigiCert Global Root G2 is present in a co-installed Oracle/OpenJDK, it will not be trusted by IBM's runtime unless explicitly added to the IBM truststore. * Windows: %JAVA_HOME%\jre\lib\security\cacerts (or ibmjsse2 keystore if configured separately) * Linux/Unix: $JAVA_HOME/jre/lib/security/cacerts

If your application server manages its own truststore (e.g. WebSphere Application Server's CellDefaultTrustStore), you must add the root certificate there via the WAS admin console under Security → SSL certificate and key management → Key stores and certificates.

Step 2: Download the Root Certificate

Download the DigiCert Global Root G2 (PEM/DER format) directly from the official DigiCert Trusted Root Authority Certificates page.

Step 3: Import via Keytool

Use the Java keytool utility to add the root to your truststore. You will likely need Administrative or Sudo privileges.

# Example command for Linux/macOS
keytool -import -alias digicertg2root -keystore $JAVA_HOME/lib/security/cacerts -file DigiCertGlobalRootG2.crt

# Example command for Windows
keytool -import -alias digicertg2root -keystore "%JAVA_HOME%\\lib\\security\\cacerts" -file DigiCertGlobalRootG2.crt

4. Long-Term Recommendation

Because the certificate is renewed approximately every 6 months and no advance notification is sent, we strongly recommend making your integration resilient to routine rotation rather than relying on a one-time fix.

Do not use certificate pinning

Certificate pinning — where your application trusts only a specific certificate thumbprint — will cause your integration to break on every renewal. Remove any pinned thumbprints and instead trust the CA chain.

Trust the CA chain, not the leaf certificate

Your truststore should include the root authority (DigiCert Global Root G2) rather than the end-entity certificate for api.nps.today. Trusting the root means any certificate we issue under that chain — including future renewals — will be accepted automatically without any changes on your end.

Keep your JRE/JDK updated

Modern Java releases (Java 8 update 141 and later, Java 11, Java 17, and Java 21) include DigiCert Global Root G2 in their default cacerts file. Keeping your runtime up to date is the lowest-effort way to stay compatible with future renewals.