How IP Lists scope admin, agent and API access per user group

A common mistake is treating IP whitelisting in VICIdial as a single on or off switch. It isn't. Every User group carries three separate whitelists, and each governs a different way of reaching the system. Once you see them as independent gates, the design makes sense.

Three gates, three jobs

On the user group modify screen you'll find Admin IP Whitelist, Agent IP Whitelist and API IP Whitelist. All three default to DISABLED, which is why a fresh system lets people log in from anywhere. Enable one and point it at an IP List, and only the addresses in that list can use that surface.

• Admin: restricts the administration web screens, where managers build campaigns and load leads.
• Agent: restricts the agent screens where an Agent logs in to take and place calls.
• API: restricts programmatic calls through the Agent API and the Non-agent API.

Why scope them separately

Different roles in the same group reach VICIdial from different places. Agents in a remote outbound team may log in from home, so you leave Agent IP Whitelist DISABLED. The two managers who run that team always work from the office, so you enable Admin IP Whitelist and assign a one-address list. Meanwhile your CRM integration that fires the API runs from a fixed server, so you enable API IP Whitelist with that single server IP. One group, three different security postures.

flowchart TD
  A[Authenticated request] --> B{Which surface}
  B -->|Admin screen| C{Admin whitelist on}
  B -->|Agent screen| D{Agent whitelist on}
  B -->|API call| E{API whitelist on}
  C -->|No| P[Allow]
  C -->|Yes| F{IP in list}
  D -->|No| P
  D -->|Yes| F
  E -->|No| P
  E -->|Yes| F
  F -->|Yes| P
  F -->|No| Q[Block]

The internal-IP gotcha

Warning: some functions of the API (application programming interface) run from the servers themselves, not from an outside client. If you enable the API IP Whitelist, add your internal server IP addresses to the list, or those background functions stop working. The same logic applies to agent-side Dispo Call URL actions, which execute from the web server and need the web server's IP present.

Because the whitelist check runs after authentication, you can also flag one specific user to ignore IP Lists entirely. That keeps the gate strict for the group while letting a trusted person connect from anywhere. Use that exception sparingly and document who has it, since each ignore flag is a small hole in the policy you just built.

Plan your lists before you assign them

Because three surfaces and several groups can share lists, it pays to name them by purpose rather than by group. A list called office_admins or integration_servers stays meaningful as teams reorganize, where a list named after one department gets confusing the moment two groups need the same addresses. You can reuse a single well-named list across many group whitelists, which keeps the address set in one place instead of copied around. When the office IP changes, you update one list and every gate that points at it follows.

Start permissive and tighten gradually. Enable the admin gate first, confirm managers can still work, then move to the agent and API gates one at a time. Turning on all three at once on a busy floor is how you generate a wave of lockout tickets and end up disabling the whole feature in a panic.

IP scoping sits alongside the other group-level controls. The users and groups multi-team guide ties them together, and you can pair IP rules with campaign access by reading how allowed campaigns are scoped per group.

If you'd rather skip the server setup and get a hardened dialer that already serves all three surfaces over HTTPS, see VICIfast pricing and provision your own box in under 40 seconds.