Application Authorization and Integration Start
- esnata (Unlicensed)
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:
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 |
|---|---|
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 a80f1e618ddd4d4584e2bd48fd404194App 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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 →