When to use an API Only User account

Every integration you bolt onto VICIdial needs an account to authenticate with. The instinct is to reuse a manager login or spin up a normal agent. Both are a security mistake. The API Only User setting exists precisely so a service account can talk to the API and nothing else. This post covers what it blocks, when to reach for it, and how it pairs with the rest of the API permissions.

What the setting does

When you enable API Only User on an account, that account can no longer log into the admin web screen or the agent screen. The credentials still work for API (application programming interface) requests, but a human cannot use them to sit at a real interface. It is off by default; you turn it on deliberately for accounts that should only ever be reached by code.

Think of it as the difference between a person's login and a service account. A person needs the screens. A wallboard, a CRM connector, or a lead-loading script does not, and locking those credentials out of the UI removes a whole class of risk if they ever leak.

When to use it

• The dedicated account behind any Agent API integration that pauses, hangs up, or disposition agents from an outside tool.
• A Lead loader or nightly script that posts new Lead records into a Campaign over the non-agent API.
• A reporting connector or Webhook consumer that pulls stats but should never be able to drive a live session by hand.

In all three cases there is no reason a human should log in as that account, so closing the screens removes a door without removing any function the integration needs.

The setting also keeps your audit trail honest. A service account that can never sit at a screen will only ever show up in API logs, so when you are tracing who paused a stuck session or who pushed last night's leads, you are not sifting through a login that might be a person one minute and a script the next. That clarity pays off the first time something goes wrong at 2am and you need to know exactly which integration touched the system.

How the login decision plays out

flowchart TD
  A[Login or API request] --> B{API Only User on}
  B -->|no| C{Which surface}
  C -->|admin or agent screen| D[Allowed]
  C -->|API call| D
  B -->|yes| E{Which surface}
  E -->|admin or agent screen| F[Blocked]
  E -->|API call| G[Allowed]

Pair it with least privilege

API Only User controls where the account can go, not what it can do once it is in. Combine it with the other API controls so the account is both screen-locked and narrowly scoped:

1. Turn on Agent API Access if the account must drive live agent sessions.
2. Set API List Restrict so lead commands stay inside the campaigns of that account's User group.
3. Trim API Allowed Functions down to only the commands the integration actually sends.

Give each integration its own API Only account too. Shared service credentials make it impossible to tell which tool did what when you are reading the logs later.

Where this fits

API Only User is part of the same permission block you set when you build any account. For the full picture of levels, groups, and isolating teams on one server, read our guide to VICIdial users and multi-team groups. And when you are creating that service account, our walkthrough on how to add a VICIdial user covers the rest of the form.

Want a hosted box where integrations and service accounts are first-class from day one? Look over our pricing and plans.