Skip to main content

How to Use API Keys on the PBX API

· 7 min read
Alex Klimenko
Alex Klimenko
Software Engineer

Use Company API Keys to automate PBX configuration and management through the PBX API.

For creating keys, general scope concepts, and cloud API usage, see the Wildix API Keys developer guide.

Table of Contents​

Prerequisites​

  • WMS 7.09 or higher
  • A Company API Key with PBX scopes (for example colleagues:read, pbx:*)

See the API Keys developer guide for key creation and management.

Authentication​

Send requests to your PBX hostname using Bearer format — the same header convention as Wildix cloud APIs:

Authorization: Bearer wsk-v1-...

Key format: 100 characters, prefix wsk-v1- followed by 93 alphanumeric characters.

curl -X GET "https://mypbx.wildixin.com/api/v1/colleagues/" \
  -H "Authorization: Bearer wsk-v1-your-api-key-here" \
  -H "Content-Type: application/json"

The mapping below lists public routes from the PBX API reference that accept Company API Keys.

PBX scopes​

Required scope depends on HTTP method and route group:

  • GET / HEAD → {resource}:read
  • Other methods → {resource}:*

Each route also accepts PBX-wide scopes that cover multiple resources:

  • Read routes accept pbx:read and pbx:*
  • Write routes accept pbx:*

When creating a key, assign the narrowest scope that covers your integration.

Scope to routes mapping​

Public PBX API routes that accept Company API Keys. Last updated: 2026-05-28.

109 routes across 25 scopes.

aclgroups:read​

View ACL groups

MethodRoute
GET/api/v1/pbx/aclgroups/
GET/api/v1/pbx/aclgroups/permissions/
GET/api/v1/pbx/aclgroups/rules/

aclgroups:*​

Full access to ACL groups, including viewing, creating, editing, and deleting

MethodRoute
POST/api/v1/pbx/aclgroups/

callcontrol:read​

View call control state

MethodRoute
GET/api/v2/call-control/list-calls/
GET/api/v2/call-control/list-devices/

callcontrol:*​

Control active calls

MethodRoute
POST/api/v2/call-control/answer/
POST/api/v2/call-control/attendant-transfer/
POST/api/v2/call-control/blind-transfer/
POST/api/v2/call-control/dtmf/
POST/api/v2/call-control/hangup/
POST/api/v2/call-control/hold/
POST/api/v2/call-control/make-call/
PUT/api/v2/call-control/set-active-device/
POST/api/v2/call-control/unhold/
POST/api/v2/call-control/update-contact-info/

callgroups:read​

View call groups

MethodRoute
GET/api/v1/dialplan/callgroups/
GET/api/v1/dialplan/callgroups/{id}/stat/
GET/api/v1/pbx/settings/callqueues/
GET/api/v1/pbx/settings/callqueues/{id}/

callgroups:*​

Full access to call groups, including viewing, creating, editing, and deleting

MethodRoute
POST/api/v1/dialplan/callgroups/
DELETE/api/v1/dialplan/callgroups/{id}/
PUT/api/v1/dialplan/callgroups/{id}/
POST/api/v1/pbx/settings/callqueues/{id}/members/dynamic/
DELETE/api/v1/pbx/settings/callqueues/{id}/members/dynamic/{member}/

callhistory:read​

View call history

MethodRoute
GET/api/v1/pbx/callhistory/

colleagues:read​

View colleagues and their settings

MethodRoute
GET/api/v1/colleagues/
GET/api/v1/colleagues/{id}/
GET/api/v1/pbx/colleagues/
GET/api/v1/pbx/colleagues/{id}/

colleagues:*​

Full access to colleagues, including viewing, creating, editing, and deleting

MethodRoute
POST/api/v1/pbx/colleagues/
DELETE/api/v1/pbx/colleagues/{id}/
PUT/api/v1/pbx/colleagues/{id}/
PUT/api/v1/pbx/colleagues/{id}/preferences/
PUT/api/v1/pbx/presence/

devices:read​

View devices and device settings

MethodRoute
GET/api/v1/devices/
GET/api/v1/devices/verify/

devices:*​

Full access to devices, including viewing, creating, editing, deleting, and device operations

MethodRoute
POST/api/v1/device/resettoken/
POST/api/v1/devices/
POST/api/v1/devices/scan/

dialplan:read​

View dialplans and routing rules

MethodRoute
GET/api/v1/dialplan/generalsettings/
GET/api/v1/dialplan/ivr/
GET/api/v1/dialplan/paginggroups/
GET/api/v1/dialplan/switches/
GET/api/v1/dialplan/timetables/
GET/api/v1/pbx/dialplans/
GET/api/v1/pbx/dialplans/{id}/

dialplan:*​

Full access to dialplans, including viewing, creating, editing, and deleting

MethodRoute
PUT/api/v1/dialplan/generalsettings/
POST/api/v1/dialplan/ivr/
DELETE/api/v1/dialplan/ivr/{id}/
PUT/api/v1/dialplan/ivr/{id}/
POST/api/v1/dialplan/paginggroups/
DELETE/api/v1/dialplan/paginggroups/{id}/
PUT/api/v1/dialplan/paginggroups/{id}/
POST/api/v1/dialplan/switches/
DELETE/api/v1/dialplan/switches/{id}/
PUT/api/v1/dialplan/switches/{id}/
POST/api/v1/dialplan/timetables/
DELETE/api/v1/dialplan/timetables/{id}/
PUT/api/v1/dialplan/timetables/{id}/
PUT/api/v1/dialplan/timetables/import/
POST/api/v1/pbx/dialplans/
PUT/api/v1/pbx/dialplans/{id}/
DELETE/api/v1/pbx/dialplans/{ids}/

info:read​

View PBX information and diagnostics

MethodRoute
GET/api/v1/departments/
GET/api/v1/dictionaries/
GET/api/v1/pbx/candidates/
GET/api/v1/pbx/ports/status/
GET/api/v1/pbx/version/

pbxpower:*​

Reboot or power off the PBX

MethodRoute
PUT/api/v1/pbx/system/reboot/

phonebooks:read​

View phonebooks and contacts

MethodRoute
GET/api/v1/contacts/
GET/api/v1/phonebooks/
GET/api/v1/phonebooks/{id}/
GET/api/v1/phonebooks/{phonebookid}/contacts/
GET/api/v1/phonebooks/{phonebookid}/contacts/{contactid}/

phonebooks:*​

Full access to phonebooks, including viewing, creating, editing, and deleting

MethodRoute
POST/api/v1/contacts/
POST/api/v1/phonebooks/
POST/api/v1/phonebooks/{phonebookid}/contacts/
DELETE/api/v1/phonebooks/{phonebookid}/contacts/{contactid}/
PUT/api/v1/phonebooks/{phonebookid}/contacts/{contactid}/

recordings:read​

View call recordings

MethodRoute
GET/api/v1/pbx/recordings/
GET/api/v1/pbx/recordings/download/{id}/

recordings:*​

Manage call recording downloads

MethodRoute
POST/api/v1/pbx/recordings/download/

smtp:read​

View SMTP settings

MethodRoute
GET/api/v1/pbx/settings/smtp/
GET/api/v1/pbx/settings/smtp/test/status/{testid}/

smtp:*​

View and modify SMTP settings

MethodRoute
PUT/api/v1/pbx/settings/smtp/
POST/api/v1/pbx/settings/smtp/test/

sounds:read​

View sounds and prompts

MethodRoute
GET/api/v1/sounds/{path}/

sounds:*​

Full access to sounds and prompts, including viewing, creating, editing, and deleting

MethodRoute
POST/api/v1/sounds/
DELETE/api/v1/sounds/{path}/
PUT/api/v1/sounds/{path}/
POST/api/v1/sounds/directory/

trunks:read​

View SIP trunks, price lists, and trunk settings

MethodRoute
GET/api/v1/trunks/fxo/
GET/api/v1/trunks/groups/
GET/api/v1/trunks/prices/
GET/api/v1/trunks/prices/{id}/export/
GET/api/v1/trunks/pstn/
GET/api/v1/trunks/sip/

trunks:*​

Full access to trunks, including viewing, creating, editing, and deleting

MethodRoute
PUT/api/v1/trunks/fxo/{id}/
POST/api/v1/trunks/groups/
DELETE/api/v1/trunks/groups/{id}/
PUT/api/v1/trunks/groups/{id}/
POST/api/v1/trunks/prices/
DELETE/api/v1/trunks/prices/{id}/
POST/api/v1/trunks/prices/{id}/
PUT/api/v1/trunks/pstn/{id}/
POST/api/v1/trunks/sip/
DELETE/api/v1/trunks/sip/{id}/
PUT/api/v1/trunks/sip/{id}/

Examples​

Read colleagues​

Requires colleagues:read (or PBX-wide read scope pbx:read):

curl "https://mypbx.wildixin.com/api/v1/colleagues/" \
  -H "Authorization: Bearer wsk-v1-your-api-key-here"

Update a device​

Requires devices:* (or PBX-wide full access scope pbx:*):

curl -X PUT "https://mypbx.wildixin.com/api/v1/device/{id}/" \
  -H "Authorization: Bearer wsk-v1-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated device name"}'

Errors and troubleshooting​

StatusMeaning
401Missing, malformed, expired, or unknown key
403Valid key, but route is unsupported or key lacks the required scope

Common fixes:

  1. Confirm the key includes the PBX scope for the target route (see mapping above)
  2. Use GET/HEAD with {resource}:read scopes; use {resource}:* for writes
  3. Check key expiration in WMS

See also: Wildix API Keys developer guide · PBX API reference