OKTA000 - Failed to Connect to Okta

Agent error code #OKTA000 indicates that the agent could not reach the Okta REST API at the configured domain. The request failed before any authentication or network-zone operation could take place.

This error is distinct from authentication failures (#OKTA001), authorization failures (#OKTA002), TLS errors (#OKTA003), and timeouts (#OKTA004). It indicates a general connectivity failure such as connection refused or DNS resolution failure.

Common causes include:

• The Okta Domain in the Knocknoc backend has a typo, includes a scheme/path, or refers to a deleted org
• The agent host cannot resolve *.okta.com (or *.oktapreview.com for preview orgs)
• An outbound proxy or egress firewall is blocking traffic to the Okta API
• A transient outage at Okta. Check the Okta Trust page

Steps to Resolve

Verify the Okta Domain

1. In the Knocknoc admin interface, open the backend configuration for the affected Okta Knoc
2. Confirm the Okta Domain is in the form acme.okta.com (no https://, no trailing slash, no /api/... path)
3. If your org is on Okta's EMEA or Preview cells, the suffix may differ (e.g. acme.okta-emea.com, acme.oktapreview.com)

For the full setup, see the Okta setup guide.

Test Connectivity From the Agent Host

1. From the host running the Knocknoc agent, run: curl -v https://<your-domain>/api/v1/users/me
2. The expected response is HTTP 401 (no token supplied). That confirms connectivity. A connection refused or DNS error indicates a network problem to fix before retrying in Knocknoc

Allow Outbound Traffic to Okta

The agent needs HTTPS (TCP 443) access to your Okta org's domain. Okta does not publish a stable list of egress IPs for its API endpoints; allow by hostname where possible.

Configure a Proxy

If the agent host must reach the internet via a forward proxy, set HTTPS_PROXY in the agent environment so the Go HTTP client picks it up.

Still Having Issues?

We can help you out, contact us at support@knocknoc.io.