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:

{
  "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 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.