Типы приложений
Note |
---|
Тип “password_credentials” может быть установлен только администратором |
Приложениям с типом public доступен метод получения токена доступа через код авторизации, для чего требуется, чтобы пользователь прошел авторизацию в системе (authorization_code flow).
Приложениям с типом trusted доступен метод получения токена доступа без авторизации пользователя в системе. Приложение получит токен, связанный с пользователем, создавшим приложение (client_credentials flow).
Приложениям с типом password_credentials доступен метод получения токена доступа с помощью логина и пароля пользователя (password flow).
Уровни доступа приложений
Note |
---|
Уровень доступа “All” может быть установлен только администратором |
Существуют два уровня доступа приложений: Call API и All. Разделение приложений по уровням доступа предусмотрено из-за того, что некоторые приложения, в частности, веб-интерфейсы, ожидают, чтобы АТС клиента была сконфигурирована определенным образом, и изменения конфигурации другими приложениями могут нарушить работу такого веб-интерфейса. Поскольку, как правило, внешним приложениям не требуется изменять конфигурацию АТС, по умолчанию созданное приложение имеет уровень доступа Call API. Если же приложению требуется изменение конфигурации АТС, то возможно повысить его уровень с помощью администратора.
Уровень Call API позволяет:
получать все ресурсы (метод GET), доступные авторизованному пользователю,
создавать обработчики событий (call events),
удалять записи разговора,
удалять сообщения голосовой почты,
инициировать отправку, а также отмену и повтор отправки факсов,
удалять входящие сообщения факса,
инициировать совершение вызовов,
управлять вызовами и прерывать их.
Изменение конфигурации приложениям с уровнем Call API недоступно.
Уровень All – полный доступ, позволяет приложению получать, изменять, добавлять и удалять ресурсы, доступные авторизованному пользователю, в том числе ресурсы конфигурации. Данный уровень доступа приложению может установить только администратор.
Note |
---|
Вне зависимости от уровня доступа приложения, в случае, если у пользователя, от имени которого приложение делает запрос, установлен тип доступа “read_only”, то приложению будут разрешены только GET-запросы |
После регистрации приложения системы выведет информацию о зарегистрированном приложении, в том числе сгенерированные App ID и App secret приложения, необходимые для авторизации.
Список всех зарегистрированных пользователем приложений доступен по адресу https://<hostname>/app/
Авторизация приложения
Для авторизации приложений в системе используется протокол OAuth2.
Авторизация публичных приложений с подтверждением пользователя
Приложение перенаправляет пользователя на URL авторизации https://<hostname>/oauth/authorize, передавая данные авторизации в качестве параметров GET-запроса в формате URL-encoded.
Параметр
Описание
response_type
Тип ответа, всегда должен иметь значение code
redirect_uri
URI, по которому система будет посылать ответ. Должен совпадать с указанным при создании приложения
client_id
App ID, сгенерированный при создании приложения
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).
|
Параметры запроса
Параметр
Описание
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. Параметры передаются в теле запроса в формате applicationInfo |
---|
До получения токена доступа тело запроса передается в формате application/x-www-form-urlencoded |
|
Параметры запроса
Параметр
Описание
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 | ||
---|---|---|
| ||
{
"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). |
Более подробно про запросы к 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.
|
Параметры запроса
Параметр
Описание
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
С деталями использования токена регенерации можно ознакомиться по ссылке.