Manage your firewall from your own code

Everything in a server’s Firewall window can be done from your own code with the VICIfast API: allow or block an address on one server, on several, or on all of them at once; change the firewall settings; add scheduled country rules; lock or reset an agent’s MFA; and read agent sign-in attempts and the firewall audit log. It is on every plan.

Get a key

• In the dashboard, open API, then Keys, and create a live key (vf_live_).
• Tick firewall:read to read rules, settings, attempts and the audit log. Tick firewall:write as well to change anything.
• Optionally limit the key to the addresses your code runs from. Test keys (vf_test_) have no firewall sandbox: a firewall change costs nothing, so use a live key.

What a rule can open

• An allow rule with the agent profile (the default) opens the agent screen (443), the webphone (8089) and SIP.
• An allow rule with the carrier profile opens SIP only.
• The API never opens SSH. Admin rules, which add SSH, are added from the dashboard, and the API has no switch to turn the firewall off.
• One address per rule. Ranges are refused; to let a whole region in, add a scheduled country rule. IPv6 is refused because the server firewall cannot apply it.
• A block rule keeps an address out of every port.

Letting an agent in from home

Your own login system can let an agent in when their shift starts: POST /api/v1/servers/{server id}/firewall/rules with action allow, the agent’s ip, their vicidial_user and expires_in_hours (12 for a shift). The rule shows under that agent in the Agents tab, and an agent has one rule per address: sending it again replaces the earlier one.

Many servers at once

• POST /api/v1/firewall/rules with servers set to "all" (or a list of server ids) adds one rule everywhere, for example a new office address. Each server answers for itself, so one that already has the rule does not stop the rest.
• POST /api/v1/firewall/rules/remove takes an address off every server, for example when an agent leaves.
• GET /api/v1/firewall/rules?ip=… shows every server an address is let in on or blocked from.

Clusters

A cluster has one firewall. Name any of its servers and the rule goes in the cluster’s firewall, copied to every server it covers: all of them, or the dialers for a carrier. Deleting it removes every copy.

Webhooks

Add a webhook endpoint (API, then Webhooks) for firewall_rule.created, firewall_rule.updated, firewall_rule.deleted and firewall_rule.expired to hear about every change, from the dashboard, the API, or an agent signing in through the firewall portal or the app. Each event carries the rule and changed_via.

Reference

Every endpoint, field and error is in the API reference at /api-docs, under Firewall. Changes made through the API show in the server’s firewall audit log with the key that made them.