Типы приложений
Тип “password_credentials” может быть установлен только администратором
Приложениям с типом public доступен метод получения токена доступа через код авторизации, для чего требуется, чтобы пользователь прошел авторизацию в системе (authorization_code flow).
Приложениям с типом trusted доступен метод получения токена доступа без авторизации пользователя в системе. Приложение получит токен, связанный с пользователем, создавшим приложение (client_credentials flow).
Приложениям с типом password_credentials доступен метод получения токена доступа с помощью логина и пароля пользователя (password flow).
Уровни доступа приложений
Уровень доступа “All” может быть установлен только администратором
Существуют два уровня доступа приложений: Call API и All. Разделение приложений по уровням доступа предусмотрено из-за того, что некоторые приложения, в частности, веб-интерфейсы, ожидают, чтобы АТС клиента была сконфигурирована определенным образом, и изменения конфигурации другими приложениями могут нарушить работу такого веб-интерфейса. Поскольку, как правило, внешним приложениям не требуется изменять конфигурацию АТС, по умолчанию созданное приложение имеет уровень доступа Call API. Если же приложению требуется изменение конфигурации АТС, то возможно повысить его уровень с помощью администратора.
Уровень Call API позволяет:
получать все ресурсы (метод GET), доступные авторизованному пользователю,
создавать обработчики событий (call events),
удалять записи разговора,
удалять сообщения голосовой почты,
инициировать отправку, а также отмену и повтор отправки факсов,
удалять входящие сообщения факса,
инициировать совершение вызовов,
управлять вызовами и прерывать их.
Изменение конфигурации приложениям с уровнем Call API недоступно.
Уровень All – полный доступ, позволяет приложению получать, изменять, добавлять и удалять ресурсы, доступные авторизованному пользователю, в том числе ресурсы конфигурации. Данный уровень доступа приложению может установить только администратор.
Вне зависимости от уровня доступа приложения, в случае, если у пользователя, от имени которого приложение делает запрос, установлен тип доступа “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
Параметры передаются в теле запроса в формате 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/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. Параметры передаются в теле запроса в формате 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:
curl \ -H "Authorization: Bearer 1sz9xnbNsgIXF5uGEeL0df2Iyec29W" \ -X GET https://hostname/api/ver1.0/user/
Ответ системы:
{ "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 }
Использования токена регенерации (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 | Refresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен |
← Пользователи и полномочия Интерактивный обозреватель API →