Debugging HTTPS calls on iOS and iPadOS usually means reaching for a TLS proxy that can show you encrypted payloads. Charles Proxy remains a reliable option because it integrates with Apple devices, supports on-the-fly rewriting, and lets you archive sessions for later analysis. This guide walks through the minimal setup to get your device routing traffic through Charles without breaking App Transport Security (ATS).

Prerequisites#

  • Charles Proxy 4.6 or newer installed on your Mac.
  • The iOS or iPadOS device connected to the same Wi‑Fi network as the Mac running Charles.
  • Developer access to the app you are testing so you can safely tweak networking settings if needed.

Configure the Wi‑Fi proxy on the device#

  1. Open Settings → Wi‑Fi on your device and tap the ℹ︎ icon next to the active network.
  2. Scroll to Configure Proxy and choose Manual.
  3. Enter your Mac’s local IP address in Server. You can find it in System Settings → Network or by running ipconfig getifaddr en0 on macOS.
  4. Set Port to 8888 (Charles’ default) and leave Authentication off unless you enabled it in Charles.
  5. Tap Save. Traffic now routes through your Mac for that Wi‑Fi network only.

Keep Charles open; if the proxy stops listening, iOS calls will fail immediately with NSURLErrorCannotConnectToHost.

Install and trust the Charles SSL certificate#

Charles needs to present its own certificate so it can decrypt HTTPS. Apple treats any custom certificate as untrusted until you explicitly approve it.

  1. On the device, open Safari and navigate to https://chls.pro/ssl.
  2. Safari downloads a configuration profile and shows an Profile Downloaded banner. Tap it or go to Settings → General → VPN & Device Management.
  3. Under Downloaded Profile, select Charles Proxy CA and tap Install. Confirm with your passcode and approve the warning prompts.
  4. Navigate to Settings → General → About → Certificate Trust Settings.
  5. Under Enable Full Trust For Root Certificates, toggle on Charles Proxy CA and confirm. Without this step, every HTTPS connection will fail due to trust errors.

Once trusted, Charles can decrypt traffic for domains that permit re-signing. ATS exceptions are unnecessary unless the app pins certificates or forbids proxies.

Verify the capture#

  1. In Charles, hit the Start Recording button (red circle). Leave Proxy → macOS Proxy off when you only care about physical devices; toggle it on if you also want macOS apps or simulators to route through Charles.
  2. Launch your app and repeat the network flow you want to inspect.
  3. Requests should stream into Charles’ session list. Double-click an entry to view request headers, response payloads, and TLS information.
  4. Use Tools → SSL Proxying Settings to add specific hosts if Charles reports SSL handshake failed. Add domains with wildcards (for example, api.example.com or *.example.com).

If your traceroute stays empty, confirm the device still uses the same Wi‑Fi network and that no VPN profiles override your proxy settings.

Troubleshooting tips#

  • Certificate pinning: Apps that implement SSL pinning will reject Charles’ certificate. Disable pinning in a debug build or use a build flavor without pinning to capture traffic.
  • HTTP/3 traffic: Charles downgrades HTTP/3 to HTTP/2. If your API strictly requires QUIC, test with Apple’s PacketLogger or consider Proxyman/mitmproxy with HTTP/3 support.
  • Background sessions: Background URLSession traffic may not route through the proxy when the app is suspended. Keep the screen awake or use Instruments’ HTTP template for background captures.
  • Different networks: Switching Wi‑Fi networks clears the proxy configuration. Re-apply the manual proxy after every network change.

Clean up when finished#

  1. Return to Settings → Wi‑Fi → (ℹ︎) and set Configure Proxy back to Off (or Automatic).
  2. In Settings → General → About → Certificate Trust Settings, disable the Charles Proxy CA toggle.
  3. Optionally remove the profile from VPN & Device Management to keep the device’s trust store clean.

Resetting both the proxy and certificate ensures future HTTPS requests use your production trust chain and keeps users from accidentally routing through a dormant proxy.

With these steps in place you can capture, inspect, and replay network flows directly from real devices, which is invaluable when simulator behavior diverges from field reports.