Getting Started with the API PBX

This introduction contains a brief description to help you start interacting with API PBX.

We currently recognize 2 types of APIs:

  • IPBX API - centralized API containing a wide range of management/configuration options

  • Local API (deprecated) - API running on each PBX, it will be a part of IPBX API in the future

1. Creating API Access

You can create API access in the IPEX Portal https://portal.voipex.io/.

You choose API access in the section For Developers.

You can create your API access by pressing the button in the top right corner “Create access”.

You need to fill in this information:

  • E-mail - write your username

  • Password - you can choose between custom or use generated, if needed, press the question mark to get help

  • Switchboard - select by clicking the arrow on the right

  • Impersonation - by checking Impersonation, you will get  access to all user's API functions and you can impersonate a user

  • - if you leave the box unchecked, you will only have access to the Rest api (calls log, switchboard)

 

 

2. Authorization

Our API uses OAuth 2.0 password grant flow to allow you to access data from .. .

Obtaining a Token

The access token is obtained by making POST request to authorization endpoint https://auth.voipex.io/token. The post body must be formatted by using x-www-form-urlencoded.

Parameter

Value

Parameter

Value

grant_type

password

client_id

api

username

<access_email>

password

<access_password>

scope

openid profile

Example:

curl -d "grant_type=password&client_id=api&username=<access_email>&password=<access_password>" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://auth.voipex.io/token

Refreshing a Token

The access token is valid for 50 minutes. After that time the client needs to obtain a new access token by using refresh_token and making aPOST request to authorization endpoint URL (https://auth.voipex.io/token). The post body for this specific method must also be formatted by using x-www-form-urlencoded.

Parameter

Value

Parameter

Value

grant_type

refresh_token

client_id

api

refresh_token

<refresh_token>

Example:

curl --location --request POST 'https://auth.voipex.io/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=api' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'refresh_token=eyJhb...'

Impersonification

POST request to https://auth.voipex.io/token-exchange. Access e-mail is e-mail of user for whom the impersonation will be performed. The impersonification can be performed by the user who has impersonation enabled in the api access.

Parameter

Value

Parameter

Value

email

<email/login assigned to a user that you want to impersonate>

Example

curl --location --request POST 'https://auth.voipex.io/token-exchange' --header 'Authorization: Bearer eyJhb...' --header 'Content-Type: application/json' --data-raw '{"email": "<email>"}'

3. Using our API

Access token is provided in Authorization header with every request in Bearer <access_token> format. The best way to try our API is to visit the documentation page. Before making requests, copy your token to the input field in topbar (do not forget to add Bearer before the token).