What the Agent API Access permission does

If you want a wallboard, a CRM screen pop, or a custom button to control what an agent's screen is doing, you reach for the VICIdial agent API. The catch is that an account can't send API commands until someone flips the Agent API Access permission on. This post explains what that one checkbox unlocks and the two-account rule that trips up almost everyone the first time.

What the permission actually grants

The agent API is a set of HTTP commands that act on a live agent session: pause and resume, hang up the current call, change disposition, dial a number, transfer, and so on. The Agent API only obeys commands when the account behind the request is allowed to issue them. Agent API Access is that allow flag. Turn it on for an account and that account may send commands; leave it off and every call returns an error, even if the request is otherwise perfectly formed.

Worth noting: this is the agent-facing half of the API. The non-agent half (reporting, lead loading) is governed separately, so a wallboard that only reads stats may not need this flag at all.

The two-account rule

Here is the part people get wrong. The account that holds Agent API Access is NOT the agent whose session you are controlling. You always need two accounts: an API user that carries the permission and authenticates the request, and a separate agent whose live Agent session is the target. The API user supplies the credentials; the agent user is named as the subject of the command. Trying to use one account for both roles fails.

So a normal setup is: one dedicated API user (often paired with the API Only flag so it can never log into a screen), plus your everyday agents who never touch the API directly. Your integration sends commands as the API user, naming the live agent as the target.

How a command flows

sequenceDiagram
  Integration->>VICIdial: API call as API user plus target agent
  VICIdial->>DB: Check API user has Agent API Access
  DB-->>VICIdial: Allowed
  VICIdial->>Session: Apply command to target agent
  Session-->>VICIdial: Pause or hangup done
  VICIdial-->>Integration: Success response

Scoping it down

Granting access is not all-or-nothing. Two companion settings narrow what the API user can do:

• API List Restrict limits lead and list commands to the lists inside the campaigns allowed for that user's User group. Useful when many teams share one box and you do not want a screen pop reaching another team's leads.
• API Allowed Functions restricts the command set. Default is everything; tighten it so a pop-only integration can pause and disposition but never load a Lead list or pull a Real-time report.

Treat the API user like any other privileged account: unique password, least privilege, and a clear name so it shows up in audit trails.

Where this fits

Agent API Access is one permission among many on the user record, and it pairs naturally with the API Only flag. For the wider picture of roles, levels, and team isolation, read our guide to VICIdial users and multi-team groups. If you are still mapping out what each permission checkbox controls, the user permission matrix walkthrough covers the rest of the grid.

Running integrations cleanly is far easier on a box you do not have to babysit. See our plans and pricing for managed VICIdial servers that come API-ready out of the gate.