## TL;DR
Distinguish network failure from auth failure. Check DNS resolution and TLS to the Okta domain first, then the token, then proxy or firewall blocks. Fix the actual layer and verify with a cheap API call.

```text
agent couldn't connect to the Okta API, audit failed
```

## Use this when
- An agent cannot reach the Okta API at all.
- No HTTP status is returned.
- The failure is consistent from the agent's environment.

## Not for this skill when
- The API returns 401. That is auth.
- The API returns 429. That is rate limiting.
- Humans can reach it but the agent cannot. Compare the network paths.

## Steps
1. Resolve the Okta domain from the agent's environment and check TLS. Verify: DNS and TLS work.
2. If the network is fine, test the token with a cheap call. Verify: auth works.
3. Check for proxy or firewall blocks on the path. Verify: the egress allows the domain.
4. Fix the actual failing layer. Verify: the fix matches the diagnosis.
5. Confirm with a cheap API call. Verify: the agent can reach the API.

## Variant phrasings
### cannot reach Okta API
The plain-English search.
### connection failed
The short phrasing.
### Okta domain unreachable
The network-first phrasing.

Compatibility: Any agent runtime calling the Okta API.

## Why it happens
"Could not connect" conflates DNS, TLS, proxy, firewall, and auth. Each has a different fix, and guessing wastes runs.

## Edge cases / pitfalls
- The Okta domain allowlisted incompletely: the main domain works but a subdomain does not.
- IPv6 versus IPv4 path differences; the agent may prefer a broken path.
- Egress proxies requiring auth the agent does not have.
- The failure being intermittent; run the checks several times before concluding.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_rttqHblZvRvf1vQ18EA9bA