Self Signed Certificates
When using the Descope SDKs behind corporate proxies, local development tunnels, or internal environments that inject self-signed certificates, TLS verification may fail.
Typical symptoms include SDK calls failing with messages such as:
self-signed certificate in certificate chainx509: certificate signed by unknown authorityCERTIFICATE_VERIFY_FAILEDSSLHandshakeException
This guide explains why this happens and how to resolve it safely across supported SDKs.
Disabling TLS verification (e.g., setting NODE_TLS_REJECT_UNAUTHORIZED=0, verify=False, or InsecureSkipVerify) exposes your application to man-in-the-middle attacks.
Do not use these workarounds in production. Instead, configure your system to trust the certificate properly.
Common Errors by SDK
| SDK | Common Error Message |
|---|---|
| Node.js | FetchError: request to https://api.descope.com/v2/keys/YOUR_DESCOPE_PROJECT_ID failed, reason: self-signed certificate in certificate chain |
| Python | requests.exceptions.SSLError: HTTPSConnectionPool(host='api.descope.com', port=443): Max retries exceeded with url: /v2/keys/YOUR_DESCOPE_PROJECT_ID (Caused by SSLError(SSLError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain'))) |
| Java | javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target |
| Go | Get "https://api.descope.com/v2/keys/YOUR_DESCOPE_PROJECT_ID": x509: certificate signed by unknown authority |
| .NET | System.Net.Http.HttpRequestException: The SSL connection could not be established, see inner exception. ---> System.Security.Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure. |
Recommended Solution: Trust the Certificate
The most secure and portable approach is to make your runtime trust the signing certificate:
- Obtain the self-signed/root CA certificate used by your proxy or development server (usually a
.crt/.pem). - Add it to the OS trust store or configure your language/runtime to trust it (see SDK-specific instructions below).
- Restart your app so the new trust settings are picked up.
This approach properly configures your application to trust your corporate CA or self-signed certificates while maintaining security.
Alternatively, install the CA into the OS trust store so Node picks it up automatically.
Temporary Development Workarounds (Not for Production)
If you must proceed quickly in local development, you can temporarily relax TLS checks. However, we strongly recommend using the secure approach above for production environments.
Warning
These approaches disable SSL certificate validation and should never be used in production environments. They create security vulnerabilities by accepting any certificate.
This affects all HTTPS requests in the process, not just Descope.