How to secure the VICIdial API with HTTPS and a dedicated user

Two simple steps protect your VICIdial API: serve it over HTTPS so credentials are not exposed, and call it from a narrow, purpose-built user account.

The VICIdial API is convenient because everything rides in a web address. That is also the risk: your username and password sit right there in the URL (in VICIdial). Two steps close most of the gap — encrypt the connection and use an account that can do only what it must. Neither step is hard, and skipping either is the kind of shortcut that bites later.

Think of it as two locks on the same door. The first protects the credential while it travels; the second limits what that credential can do if it is ever lost. You want both, because each covers a gap the other leaves open.

Step one: always use HTTPS

The Non-agent API can run over HTTPS whenever your web server is set up for it. The change is just the scheme at the front of the call:

curl "https://server/vicidial/non_agent_api.php?source=myapp&function=version&user=6666&pass=1234"

Over plain http, anyone able to watch the traffic between your app and the server reads those credentials in the clear. Over https, the whole request is encrypted, so the login, password, and any Lead data are hidden in transit. The API supports HTTPS whenever the web server in front of it is configured for it; you do not change any function or parameter, only the address you point at.

Never send API calls over plain HTTP outside a trusted local network. A single captured request hands an attacker a working API login and password.

Step two: a dedicated, narrow user

Every API action requires the login and password of an API-enabled VICIdial user. Do not reuse a human administrator login for this. Create one account that exists only for your integration, enable API access on it, and give it the smallest user level and the fewest permission checkboxes that still let your scripts run. If that account ever leaks, the blast radius is limited to exactly the functions it was allowed to call.

Two more habits help. Give each integration its own source label so you can trace activity per app in the logs, and review what your API user can do whenever the integration changes. If a script stops needing the modify-campaigns permission, take it back. The goal is a user that can do precisely what it must, and nothing extra.

sequenceDiagram
    participant App as Your app
    participant TLS as HTTPS layer
    participant API as non_agent_api.php
    participant DB as VICIdial database
    App->>TLS: Encrypt request with credentials
    TLS->>API: Decrypted only at the server
    API->>API: Verify dedicated API user and scope
    API->>DB: Run only allowed action
    DB-->>API: Result
    API-->>App: SUCCESS or ERROR

These two habits reinforce each other. HTTPS keeps the credential from being stolen on the wire; a narrow account keeps a stolen credential from doing much. Skip the first and a sniffed request hands over a working login. Skip the second and that login can do anything an administrator can. Together they turn a single leaked URL from a disaster into a contained, low-value event. For exactly which levels and checkboxes a function expects, read API user levels and permissions explained.

For where API security sits in the wider API (application programming interface) and AGI (Asterisk Gateway Interface) picture, read the VICIdial API and AGI overview. Managed VICIfast servers arrive with HTTPS already issued and active, so the encrypted half of this is done before you log in — see the pricing page.