Для того, чтобы стороннее приложение могло использовать ресурсы системы, его необходимо создать и авторизовать

Создание приложения

Для создания приложения нужно перейти по адресу https://<hostname>/app/register, предварительно может понадобится ввод логина и пароля.

В форме регистрации требуется ввести имя (Application name) приложения, URL перенаправления (Redirect URL) для авторизации (возможно указать несколько через пробел или не указывать ни одного), выбрать тип приложения (Application Type)  – public, trusted или password_credentials, а также указать уровень доступа приложения  (Application Access) – Call API или All.

Типы приложений

Тип приложения определяет допустимые методы получения токена доступа.

Приложениям с типом public доступен метод получения токена доступа через код авторизации, для чего требуется, чтобы пользователь прошел авторизацию в системе (authorization_code flow). 

Приложениям с типом trusted доступен метод получения токена доступа без авторизации пользователя в системе. Приложение получит токен, связанный с пользователем, создавшим приложение (client_credentials flow).

Приложениям с типом password_credentials доступен метод получения токена доступа с помощью логина и пароля пользователя (password flow).

Уровни доступа приложений

Существуют два уровня доступа приложений: Call API и All. 

Разделение приложений по уровням доступа предусмотрено из-за того, что некоторые приложения, в частности, веб-интерфейсы, ожидают, чтобы АТС клиента была сконфигурирована определенным образом, и изменения конфигурации другими приложениями могут нарушить работу такого веб-интерфейса. Поскольку, как правило, внешним приложениям не требуется изменять конфигурацию АТС, по умолчанию созданное приложение имеет уровень доступа Call API. Если же приложению требуется изменение конфигурации АТС, то возможно повысить его уровень с помощью администратора.

Уровень Call API  позволяет:

• получать все ресурсы (метод GET), доступные авторизованному пользователю,
• создавать обработчики событий (call events), 
• удалять записи разговора,
• удалять сообщения голосовой почты,
• удалять входящие сообщения факса,
• инициировать отправку (а также отмену и повтор отправки) факсов,
• инициировать совершение вызовов,
• управлять вызовами и прерывать их.

Изменение конфигурации приложениям с уровнем Call API недоступно.

Уровень All  – полный доступ –  позволяет приложению получать, изменять, добавлять и удалять ресурсы, доступные авторизованному пользователю, в том числе ресурсы конфигурации. Данный уровень доступа приложению может установить только администратор.

После регистрации приложения системы выведет информацию о зарегистрированном приложении, в том числе сгенерированные App ID и App secret приложения, необходимые для авторизации. 

Список всех зарегистрированных пользователем приложений доступен по адресу https://<hostname>/app/

Авторизация приложения

Для авторизации приложений в системе используется протокол OAuth2.

Авторизация публичных приложений с подтверждением пользователя

1. Приложение перенаправляет пользователя на URL авторизации https://<hostname>/oauth/authorize, передавая данные авторизации в качестве параметров GET-запроса в формате URL-encoded.

Пример запроса:

GET https://<hostname>/oauth/authorize?response_type=code&client_id=2bb0c19ea4df4b908cf2db51a1aea86b&redirect_uri=http%3A%2F%2Ftestsite.com%2Furl&scope=all

1. Пользователь разрешает или запрещает доступ приложению к системе от своего имени. Если пользователь не авторизован в системе, перед этим он проходит авторизацию с помощью логина и пароля.
   Если пользователь разрешает доступ, то при последующих попытках авторизации запрос на доступ появляться не будет, до тех пор, пока пользователь явно не удалит разрешение.
   
   

2. Если пользователь разрешает доступ, система перенаправляет пользователя на Redirect URL приложения, указанного при регистрации, предавая в качестве параметра запроса код для получения токена доступа.

   GET https://<apphostname>/authorized?code=SpHCEr6qiCj1kZRTvEb36qZAqWqIHz

3. Приложение делает POST-запрос на сервер системы на URL https://<hostname>/oauth/token, для получения токена доступа, используя полученный код.

   POST https://<hostname>/oauth/token

   Параметры передаются в теле запроса в формате application/x-www-form-urlencoded.

   Параметры запроса

   Параметр	Описание
   grant_type	Всегда должен иметь значение authorization_code
   code	Параметр code, полученный приложением на предыдущем шаге
   redirect_uri	URI перенаправления. Должен совпадать с одним из указанных при создании приложения
   client_id	App ID, сгенерированный при создании приложения
   client_secret	App Secret, сгенерированный при создании приложения

4. Система отвечает приложению
   
   Параметры ответа

   Параметр	Описание
   access_token	Токен доступа. Используется приложением для API-запросов
   expires_in	Период времени в секундах, в течение которого токен действителен. Если в процессе использования токена возникла ошибка авторизации, рекомендуется запросить токен заново, даже если заявленное в поле expires_in время до истечения токена еще не прошло
   token_type	Тип токена всегда имеет значение Bearer
   refresh_token	Refresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен

Авторизация доверенных приложений

Если приложение доверенное (trusted), то подтверждение пользователя не требуется, приложение получает токен доступа без участия пользователя.

Данный способ авторизации может быть полезен для создания различных скриптов автоматизации, которые исключают взаимодействие пользователя с приложением.

Для получения токена приложение должно сделать POST-запрос на URL https://<hostname>/oauth/token. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded.

POST https://<hostname>/oauth/token

Параметры запроса

Параметры ответа

Авторизация приложений через логин и пароль пользователя

Если приложение имеет тип password_credentials, то возможна авторизация данного приложения по схеме, используя логин и пароль пользователя.

Для получения токена приложение должно сделать POST-запрос на URL https://<hostname>/oauth/token. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded.

POST https://<hostname>/oauth/token

Параметры запроса

Параметры ответа

Запросы к API с токеном доступа

Полученный токен доступа необходимо передавать в заголовке Authorization в формате "Bearer <access_token>" в каждом запроса к API. Пример заголовка: 

Authorization: Bearer ykX7vsJstZkUh1x3hG5sIeRgRaICMm

Запросы к API будут выполняться от имени и с разрешениями пользователя, предоставившего доступ приложению. Если в процессе использования токена возникла ошибка авторизации, рекомендуется запросить токен заново, даже если заявленное в поле expires_in время до истечения токена еще не прошло.

Пример запроса на получение информации об авторизованном пользователе через программу curl:

curl -H "Authorization: Bearer 1sz9xnbNsgIXF5uGEeL0df2Iyec29W" https://hostname/api/ver1.0/user/

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

См. далее: Запросы к API – Быстрый старт

Использования токена регенерации (Refresh Token)

Токен доступа (access token) имеет ограниченное время жизни (передается в параметре expires_in). При авторизации публичных (public) и авторизуемых по паролю (password_credentials) приложений существует возможность регенерировать токен доступа, используя токен регенерации (refresh token). Этот подход позволяет получить новый токен доступа по истечении старого без участия пользователя, так как при регенерации токена доступа с помощью токена регерации не требуются какие-либо действия от пользователя.

Для приложений типа trusted токен регенерации отсуствует.

Токен регенерации также имеет ограниченное время жизни, и если регенерация токена не удалась (система ответит за запрос кодом 401 и сообщением "invalid_grant" в поле error), приложению необходимо повторно осуществить авторизацию.

Для получения токена доступа с помощью токена регенерации приложение должно сделать POST-запрос на URL https://<hostname>/oauth/token. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded.

POST https://<hostname>/oauth/token

Параметры запроса

Параметры ответа