Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

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

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

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

Table of Contents

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

Note

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

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

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

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

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

Note

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

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

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

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

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

Note

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

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

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

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

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

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

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

Параметр

Описание

response_type

Тип ответа, всегда должен иметь значение code

redirect_uri

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

client_id

App ID, сгенерированный при создании приложения

scope

Сфера разрешений для приложения, должен иметь значение all

Пример

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

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

3. Если пользователь разрешает доступ, система перенаправляет пользователя на Redirect URL приложения, указанного при регистрации, предавая в качестве параметра запроса код для получения токена доступа:
GET https://<apphostname>/authorized?code=SpHCEr6qiCj1kZRTvEb36qZAqWqIHz

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

Параметры передаются в теле запроса в формате Авторизация доверенных приложений

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

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

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

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

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

Параметр

Описание

grant_type

Всегда должен иметь значение authorization_code

code

Параметр code, полученный приложением на предыдущем шаге

redirect_uri

URI перенаправления. Должен совпадать с одним из указанных при создании приложения

client_id

App ID, сгенерированный при создании приложения

client_secret

App Secret, сгенерированный при создании приложения

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

Параметр

Описание

access_token

Токен доступа. Используется приложением для API-запросов

expires_in

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

token_type

Тип токена. Всегда имеет значение Bearer

refresh_token

Refresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен

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

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

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

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

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

Параметр

Описание

grant_type

Всегда должен иметь значение client_credentials

client_id

App ID, сгенерированный при создании приложения

client_secret

App Secret, сгенерированный при создании приложения

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

Параметр

Описание

access_token

Токен доступа. Используется приложением для API-запросов

expires_in

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

token_type

Тип токена всегда имеет значение Bearer

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

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

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

До получения токена доступа тело запроса передается в формате application/x-www-form-urlencoded

.

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

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

Параметр

Описание

grant_type

Всегда должен иметь значение password

client_id

App ID, сгенерированный при создании приложения

client_secret

App Secret, сгенерированный при создании приложения

username

Имя пользователя, для которого требуется авторизовать приложения

password

Пароль пользователя, для которого требуется авторизовать приложения

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

Параметр

Описание

access_token

Токен доступа. Используется приложением для API-запросов

expires_in

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

token_type

Тип токена всегда имеет значение Bearer

refresh_token

Refresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен

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

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

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

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

Code Block
curl \
-H "Authorization: Bearer 1sz9xnbNsgIXF5uGEeL0df2Iyec29W" \
-X GET https://hostname/api/ver1.0/user/

Ответ системы:

Code Block
languagejson
{
  "dealer_id": null,
  "admin": false,
  "extra_params": null,
  "access": "full",
  "extension_id": null,
  "client_id": 12,
  "extension_group_id": null,
  "timezone": "Europe/Moscow",
  "login": "client1",
  "id": 20
}
Использования

(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). Этот подход позволяет получить новый токен доступа по истечении старого без участия пользователя, так как при регенерации токена доступа с помощью токена регенерации не требуются какие-либо действия от пользователя. Для приложений типа trusted токен регенерации отсутствует.

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

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

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

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

Параметр

Описание

grant_type

Всегда должен иметь значение refresh_token

refresh_token

Значение refresh_token, полученное с токеном, который требуется регенерировать

redirect_uri

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

client_id

App ID, сгенерированный при создании приложения

client_secret

App Secret, сгенерированный при создании приложения

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

Параметр

Описание

access_token

Токен доступа. Используется приложением для API-запросов

expires_in

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

token_type

Тип токена, всегда имеет значение Bearer

refresh_token

Refresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен

С деталями использования токена регенерации можно ознакомиться по ссылке.

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