Application Authorization and Integration Start

Interaction Scheme

To provide the possibility of integration from the CRM system interface, a server authorization mechanism is provided based on the OAuth 2.0 protocol that allows you to implement secure authentication of PBX users via the virtual PBX API and to access the PBX functions from the CRM system server.

The authorization process consists of the following steps:

Opening a dialog box for the user authentication in the PBX API server.
Allowing the PBX user to access their data.
Passing the code value to the PBX API server to obtain an access token with a lifetime.
Getting by the CRM server the access token access_token with its lifetime to access the PBX API.
Creating a permanent trusted application for the PBX user.

Schematically, this process occurs as follows:

1 Interaction Scheme
2 PBX User Authentication in PBX API Server
3 Receiving Access Token
4 Creating Permanent Trusted Application
5 Receiving Access Token by Trusted Application
6 Sending Requests using Access Tokens

PBX User Authentication in PBX API Server

At the integrator request, the IP telephony provider creates an application of the dealer/administrator level of the public type (getting an access token is possible after authorizing the user in the PBX server and receiving the authorization code), specifies the redirection URI and sends to the integrator the App ID (application identifier) and App Secret (application password) of this application.

To authorize a PBX user, you must redirect the user in the CRM system pop-up window (or in a separate page) to the authorization URI https://<hostname>/oauth/authorize where hostname is the hostname of the IP telephony provider API server, passing the authorization data as the GET request parameters in the URL-encoded format:

Parameter	Description

Parameter	Description
response_type	Answer type, must always has the value code
redirect_uri	URI to send the answer by the PBX API server. It must match one of the specified URI when creating the application of the type public
client_id	App ID generated when creating an application of the type public
scope	Scope of permissions for an application of the type public , must have the value all

Example:
App ID a80f1e618ddd4d4584e2bd48fd404194
App Secret a2423941f5be408c998d5f7207570990
The address https://your_site.com is used as redirect_url

The PBX user clicks on in the appeared pop-up window the link: https://<hostname>/oauth/authorize?response_type=code&client_id=a80f1e618ddd4d4584e2bd48fd404194&redirect_uri=https%3A%2F%2Fyour_site.com&scope=all

After clicking on this link, the pop-up window should appear asking to confirm access to the PBX user data. The user clicks "Allow".

Receiving Access Token

Passing the code value to the PBX API server to obtain an access token with a lifetime\

If the PBX user allows access, the PBX API server redirects it to the application redirect_uri (your_site.com), passing the value code (the code to get the access token) as a request parameter in the form https://your_site.com/cont/url?code=aIlsm1bCglDGvQKShmJAhHrBhDyshn.

Getting this value code (aIlsm1bCglDGvQKShmJAhHrBhDyshn) means that access to the PBX is allowed and now it is possible to get an access token with its lifetime and to update it.

Getting by the CRM server the access token access_token with its lifetime to access the PBX API

To get the access token, you need to execute the POST request from the CRM system server to the address https://<hostname>/oauth/token using the received code. The options are passed in the request body in the format application/x-www-form-urlencoded:

Option	Description

Option	Description
grant_type	Must always have the value authorization_code
code	Option code received by the application of type public in the previous step
redirect_uri	Redirection URI. It must match one of the specified URI when creating the application of the type public
client_id	App ID generated when creating an application of the type public
client_secret	App Secret generated when creating an application of the type public

Example:

{
  "grant_type": "authorization_code",
  "code": "aIlsm1bCglDGvQKShmJAhHrBhDyshn",
  "client_id": "a80f1e618ddd4d4584e2bd48fd404194",
  "client_secret": "a2423941f5be408c998d5f7207570990",
  "redirect_uri": "https://your_site.com"
}

The PBX API server responds to the application of the type public. Response Options:

Option	Description

Option	Description
access_token	Access token. It is used by an application of the type public for API requests
expires_in	The time period, during which the token is valid, in seconds. If an authorization error occurs during the token usage, it is recommended to request the token again, even if the time specified in the expires_in field has not yet expired
token_type	Token type. It always has the value Bearer
refresh_token	Refresh token that may be used to regenerate the access token when it becomes invalid

In response to this request, the CRM system server will receive the access token that may be used to create a permanent trusted application of the type trusted in the PBX API server. This application is necessary for you not to have to re-request access to the PBX user account, as described above. The application of the type trusted receives the access token without user authorization in the PBX server.

Creating Permanent Trusted Application

The permanent trusted application of type trusted is created as follows. For example, the access token pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes was received before. You need to send a POST request to the address https://<hostname>/api/ver1.0/application/ with the headers:
'Content-type': 'application/json',
'Authorization': 'Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes'
and the request body in the JSON format:

{
  "name" : 'App_name',
  "type": "trusted"
}

Receiving Access Token by Trusted Application

To receive the token, the application must execute a POST request to the URL https://<hostname>/oauth/token. The options are passed in the request body in the format application/x-www-form-urlencoded:

Option	Description

Option	Description
grant_type	Must always have the value client_credentials
client_id	App ID generated when creating an application of the type public
client_secret	App Secret generated when creating an application of the type public

The PBX API server responds to the application. Response Options:

Option	Description

Option	Description
access_token	Access token. It is used by the application for API requests
expires_in	The time period, during which the token is valid.
token_type	Token type always has the value Bearer

Sending Requests using Access Tokens

The received access token must be passed in the Authorization header in the format "Bearer <access_token>" in every request to API. Example of the header:
Authorization: Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes

The requests to API will be executed on behalf of and with the permissions of the PBX user who granted access to the application. If an authorization error occurs during the token usage, it is recommended to request the token again, even if the time specified in the expires_in field has not yet expired.

An example of a request to get information about an authorized PBX user:

System response:

{
  "admin": false,
  "client_id": 12,
  "dealer_id": null,
  "extension_group_id": null,
  "extension_id": null,
  "id": 20,
  "login": "client1"
}

← Integration with External Systems Extension Number Events →