Creating and Authorizing PBX Applications
In order for a third-party application to use the system resources, it must be created and authorized.
Creating a PBX application
To create a PBX application, go to the address https://<hostname>/app/register<hostname>, where hostname is the hostname of the API server of the IP telephony provider. You may first need to enter a username and password — this is the username and password to access the interface of the virtual PBX.
In the registration form, you must enter the name (Application name) of the PBX application, the Redirect URLfor authorization (you can specify several separated by a space or not specify any), select the Application Type – public, trusted or password_credentials, and specify the access level of the PBX application (Application Access) – Call API or All.
Types of PBX applications
The “password_credentials " type can only be set by the administrator
Applications with the public type have access to a method for obtaining an access token through an authorization code, which requires that the user is authorized in the system (authorization_code flow).
Applications with the trusted type have access to a method for obtaining an access token without authorizing the user in the system. The application will receive a token associated with the user who created the application (client_credentials flow).
Applications with the password_credentials type have access to a method for obtaining an access token using the user's username and password (password flow).
Access levels of PBX applications
Access level “All” can only be installed by an administrator
There are two levels of access for PBX applications: Call API and All. The separation of PBX applications by access levels is provided due to the fact that some external applications (for example, a third-party web interface) expect the client's PBX to be configured in a certain way, and configuration changes by other applications may disrupt the operation of such a web interface. Since, as a rule, external applications do not need to change the configuration of the PBX, by default, the created PBX application has the Call API access level. If an external application needs to change the configuration of the PBX, it is possible to increase the level of the PBX application with the help of an administrator.
The Call API level allows you to:
get all resources (GET method) available to the authorized user,
create event handlers (call events),
delete conversation recordings,
delete voice mail messages,
initiate sending, as well as canceling and repeating sending of faxes,
delete incoming fax messages,
initiate calls,
manage calls and interrupt them.
Changing the configuration of PBX applications with the Call API level is not available.
The All level - full access, allows the PBX application to receive, modify, add, and delete resources available to an authorized user, including configuration resources. This level of access to the PBX application can only be set by the administrator.
Regardless of the access level of the PBX application, if the user on whose behalf this application makes a request has the “read_only " access type set, then only GET requests will be allowed to such an application
After registering the PBX application, the system displays information about the registered application, including the generated App ID and App secret of the PBX application required for authorization.
A list of all user-registered PBX applications is available at https://<hostname>/app/
Authorization of the PBX application
To authorize PBX applications in the system, the protocol is used OAuth2.
Authorization of public PBX applications with user confirmation
Authorization of trusted PBX applications
Authorization of PBX applications using the user's username and password
API requests with an access token
The received access token must be passed in the Authorization header in the format "Bearer <access_token>" in each API request.
The request parameters are passed in the application/x-www-form-urlencoded (content-type: application/x-www-form-urlencoded) format.
You can read more about API requests with an access token here.
Using the Refresh Token
The access token has a limited lifetime (passed in the expires_in parameter). When authorizing public (public) and password-authorized (password_credentials) PBX applications, it is possible to regenerate the access token using the refresh token. The details of using the regeneration token can be found here.