Skip to main content

Diagnose TLS and network failures

Use this guide when a SyAuth request fails with BAD_RECORD_MAC, a TLS error, a reset or an empty response before any HTTP status. If you receive HTTP 401, 403 or another status, use API troubleshooting.

TLS is the encrypted connection used by HTTPS. These checks are for you or technical support to diagnose a connection to api.syauth.com. They are separate from the local callback: if the browser cannot open 127.0.0.1:8080 after Approve, first check the test receiver is running.

Run the commands in Terminal or Windows Command Prompt, not in the browser. Check curl is available using the first-request instructions. Begin with one run of each request below. Keep the result of each run; repeat more times only when investigating an intermittent failure as described below.

1. Compare normal negotiation, TLS 1.2 and TLS 1.3​

Run each command separately on the affected computer, keeping the network, VPN state and curl installation unchanged. The public discovery endpoint needs no token and normally returns HTTP 200. Choose your terminal's tab; Windows examples use Command Prompt (CMD).

curl --version
curl --http1.1 --connect-timeout 10 --max-time 20 -v -i "https://api.syauth.com/e/v1/.well-known/openid-configuration"
curl --tlsv1.2 --tls-max 1.2 --http1.1 --connect-timeout 10 --max-time 20 -v -i "https://api.syauth.com/e/v1/.well-known/openid-configuration"
curl --tlsv1.3 --tls-max 1.3 --http1.1 --connect-timeout 10 --max-time 20 -v -i "https://api.syauth.com/e/v1/.well-known/openid-configuration"

The first request uses normal TLS negotiation; the next two force TLS 1.2 and TLS 1.3 respectively. All three use HTTP/1.1 and the same timeouts. -v shows connection/TLS details and errors; -i shows the HTTP response headers.

For each successful request, look for HTTP 200 and a JSON object listing login/token endpoint URLs. If all requests succeed, this run did not reproduce the connection failure. If one fails, record its exact curl error and which command produced it before changing settings. These requests use public discovery data and need no account token.

Both TLS bounds matter: --tlsv1.2 alone allows newer versions. Adding --tls-max 1.2 restricts this request to TLS 1.2. An unsupported TLS 1.3 option/backend is a local tool limitation, not evidence of a network failure. See the curl options.

Repeat each request 20 times if the failure is intermittent. Keep the UTC time, network, destination IP, negotiated TLS version, HTTP status and error for each attempt. Do not add automatic retries during diagnosis: they can hide failures. curl --version identifies its TLS backend. Different HTTP clients can use different TLS implementations; results from one client do not prove that another works.

2. Compare networks and destination addresses​

Repeat the same commands on a hotspot, then return to the original network. Leave VPN and other settings unchanged. If possible, test Ethernet on the original router with Wi-Fi disabled. Check the route selected for the destination: an installed VPN adapter alone does not show that this traffic traverses the tunnel.

If the destination IP changes, repeat the comparison with one current IP on both networks. Add --resolve "api.syauth.com:443:CURRENT_IP" to the curl requests, replacing CURRENT_IP with that address. Keep the HTTPS URL unchanged to preserve the hostname and certificate validation.

Do not save this IP in permanent application configuration. Cloudflare uses anycast: the same IP can reach different data centers on different networks. A pinned-IP comparison removes a DNS difference but does not guarantee an identical server/path. See Cloudflare routing.

3. Force TLS 1.2 temporarily on the affected connection​

For a real Developer API request, replace YOUR_DEVELOPER_TOKEN directly with your token:

curl --tlsv1.2 --tls-max 1.2 -i "https://api.syauth.com/e/v1/developer/workspaces/" -H "X-Developer-Token: YOUR_DEVELOPER_TOKEN" -H "Accept: application/json"

Repeated successful responses confirm that this request works with TLS 1.2 on the tested client/network. Compare with the same request without the restriction, or with --tlsv1.3 --tls-max 1.3, before attributing the difference to the TLS version.

If the comparison shows TLS 1.2 succeeding while TLS 1.3 fails, use the TLS 1.2 restriction as a temporary workaround for that connection. For application code, use the HTTP library's supported minimum and maximum TLS settings. Keep certificate-chain and hostname verification enabled. Enabling TLS 1.2 alongside TLS 1.3 does not force the client to choose it. Browser fetch does not expose these native TLS controls.

Retest without the restriction after resolving the network/client issue. A hotspot or Ethernet connection that passes the same tests can also serve as a temporary workaround. These results narrow the diagnosis without identifying SyAuth, the router, Windows or the VPN as the faulty component.

Information to send to support​

Provide the affected hostname/path, UTC timestamps, OS and curl versions, per-attempt results, network comparison and any request identifier received. Include the sanitized commands and whether TLS 1.2 was forced, merely enabled or not tested. Remove tokens, Authorization headers, cookies, passwords and private keys before sharing output.