Skip to main content

How to Use API Keys on the PBX API

· 8 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 user context​

When a Company API Key includes PBX scopes, you can optionally assign a PBX user extension. That user is the identity for PBX API requests (ACL and ownership context).

Key settingRequest identity
User extension setThat PBX user
User extension emptyadmin (default for new and old keys)

Scopes still control what the key can call. The assigned user controls as whom those calls run.

The extension must exist on the target PBX. If the key is bound to a user that is missing there, the PBX returns 403.

Cloud APIs ignore this field — it applies only to the PBX API.

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​

Updates in this revision:

  • PBX user context — optional user extension; empty defaults to admin
  • notifications:* — create smart notifications
  • callcontrol — additional originate routes

Public PBX API routes that accept Company API Keys. Last updated: 2026-08-04.

118 routes across 26 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/v1/originate/alarmclocks/
GET/api/v2/call-control/list-calls/
GET/api/v2/call-control/list-devices/

callcontrol:*​

Control active calls

MethodRoute
POST/api/v1/originate/
POST/api/v1/originate/alarmclocks/
DELETE/api/v1/originate/alarmclocks/{id}/
PUT/api/v1/originate/alarmclocks/{id}/
POST/api/v1/originate/call/
POST/api/v1/originate/mobility/
POST/api/v1/originate/sms/
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/

notifications:*​

Create PBX smart notifications

MethodRoute
POST/api/v1/notifications/

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, key lacks the required scope, or assigned PBX user is missing on this PBX

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. If the key has a bound user, confirm that extension still exists on the PBX
  4. Check key expiration in WMS

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