> ## Documentation Index
> Fetch the complete documentation index at: https://broker-docs.newyorkcityservers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IP Firewall

> The API IP whitelist requirement and how to configure it.

## When The IP Whitelist Is Required

The IP Whitelist setting applies to each API key. It is not a global switch.

* If **IP Whitelist** is **Disabled**, the key can authenticate from any source IP address.
* If **IP Whitelist** is **Enabled**, the source IP address must match an entry in the broker IP whitelist.
* The broker IP whitelist is shared by all API keys in the broker account.
* A whitelist entry is not linked to one key. A new entry can allow access for every key that has **IP Whitelist** enabled.

The firewall applies to Live and Sandbox keys.

## Add An IP Address

You must have the Admin role.

1. Sign in to the Broker Panel.
2. Open **API Center**.
3. Find the **API Firewall** card and select **Configure Settings**.
4. Enter the public outbound address in **IP Address**.
5. Add a **Note (Optional)** and select **Add IP**.

The note can identify the system or location. Do not put credentials or other sensitive data in the note. Each IP address must be unique in the broker whitelist.

## Enable IP Whitelist For A Key

### Existing Key

1. Add at least one IP address to the shared whitelist.
2. Find the key in the **API Keys** table.
3. Open the key's **Actions** menu.
4. Select **Enable IP Whitelist**.
5. Confirm that the **IP Whitelist** column shows **Enabled**.

The Broker Panel does not enable the setting on an existing unrestricted key when the shared whitelist is empty.

To remove the restriction, open the same menu and select **Disable IP Whitelist**. This action does not delete the shared whitelist entries.

### New Key

Select **Restrict by IP address** in the IP restriction step when you create the key. The new key uses the existing shared whitelist.

You can create a restricted key when the shared whitelist is empty. That key rejects all API requests until you add a matching address or disable the setting.

## Remove An IP Address

1. Open **API Firewall Configuration**.
2. Select one or more entries in **Whitelist Management**.
3. Select **Remove Selected**.

Removal takes effect for all restricted keys. Removing the last entry does not disable IP Whitelist. All keys with **IP Whitelist** enabled then reject all requests.

## Blocked Request Response

A valid API key from a source address that is not allowed receives HTTP `403 Forbidden`:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_permissions",
    "message": "IP address not whitelisted"
  }
}
```

The **Last Used** time for the key does not change after this firewall rejection.

A missing, malformed, inactive, expired, or invalid key receives HTTP `401` before the firewall check. Read [Authentication](/api/authentication) for API key setup and authentication errors.

## Troubleshoot A Blocked Request

1. Confirm that the request uses the expected key and that **IP Whitelist** is **Enabled** for that key.
2. Confirm the caller's current public outbound IP address. Do not use its local or inbound address.
3. Confirm that the exact address or a CIDR range containing it is in **API Firewall Configuration**.
4. Add every possible outbound address for a NAT gateway, proxy, or egress service.
5. Send `GET /v1/auth-check` from the same system and network path as the integration.

If the request still returns HTTP `403`, contact support. Provide the request time, endpoint, and key name. Do not send the API key secret.