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

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

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

Для создания приложения АТС нужно перейти по адресу https://<hostname>/app/register, где hostname — hostname API-сервера провайдера IP-телефонии. Предварительно может понадобиться ввод логина и пароля — это логин и пароль для доступа к интерфейсу виртуальной АТС.

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

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

Тип “password_credentials” может быть установлен только администратором

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

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

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

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

Уровень доступа “All” может быть установлен только администратором

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

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

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

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

Вне зависимости от уровня доступа приложения АТС, в случае, если у пользователя, от имени которого данное приложение делает запрос, установлен тип доступа “read_only”, то такому приложению будут разрешены только GET-запросы

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

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

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

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

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

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

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

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

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

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

До получения токена доступа тело запроса передается в формате application/x-www-form-urlencoded (content-type: application/x-www-form-urlencoded), а после получения токена доступа — в формате application/json (content-type: application/json).
Данное правило выполняется за некоторыми исключениями: к примеру, при использовании метода POST в ресурсах “Факс” и “Звуковые файлы” тело запроса передается в формате multipart/form-data (content-type: multipart/form-data)

Более подробно про запросы к API с токеном доступа можно прочитать здесь.

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

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

← Пользователи и полномочия Интерактивный обозреватель API →