---
description: >-
  Network-level requirements for the Remittances API — mutual TLS (mTLS) client certificates and fixed-IP allowlisting, with failure-mode troubleshooting.
---

# Connectivity

Before any request reaches the Remittances API, two edge-level requirements must be met. These are enforced at the network boundary (CDN + WAF), **not** inside the API — so a misconfiguration surfaces as a TLS handshake failure or a bare `403 Forbidden`, not one of the JSON errors documented elsewhere.

***

### 1. Mutual TLS (mTLS)

Every request must present a client certificate issued by Inyo. Requests without a valid client certificate are rejected during the TLS handshake, before HTTP is even negotiated.

During tenant provisioning you receive two files from Inyo:

| File | Purpose |
| ---- | ------- |
| `client.crt` | Your public client certificate |
| `client.key` | The matching private key — **keep secret; treat like a password** |

Configure your HTTP client to present the certificate on every request. Store the key in a secrets manager, not in your repository.

***

### 2. Fixed IP Address

Your egress IP must be on the Inyo allowlist. Requests from unlisted IPs are dropped at the WAF and return `403 Forbidden` with no JSON body.

Coordinate with Inyo **before**:

* Rotating outbound NAT gateways
* Adding new regions or availability zones
* Moving to a new hosting provider

Updating the allowlist is a quick support request with no code change — but a stale allowlist manifests as a total outage from your side.

***

### Working curl Example

Once you have the certificate files and your IP is allowlisted:

```bash
curl -sS \
  --cert /path/to/client.crt \
  --key  /path/to/client.key \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --header "Content-Type: application/json" \
  https://{FQDN}/organizations/$TENANT/people \
  --data '{ ... }'
```

***

### Common Failure Modes

| Symptom | Likely cause |
| ------- | ------------ |
| `curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL` / handshake abort | Missing, wrong, or expired client certificate (`--cert`, `--key`) |
| `403 Forbidden` with empty or HTML body | Egress IP not on the allowlist |
| `401 Unauthorized` + `{"error":"UNAUTHORIZED", ...}` | mTLS and IP checks passed, but the API key headers are missing or wrong — see [Authentication](authentication.md) |
| `403 Forbidden` + `{"error":"FORBIDDEN", ...}` | Valid credentials, but the `{tenant}` in the URL doesn't match the tenant that owns the API key, or the agent isn't approved |

> **Rule of thumb:** if you're getting a **JSON** error body, you've already cleared the mTLS and IP checks — the problem is at the application layer (credentials, payload, or business rules).