Настройка токенов доступа в hoster API

hoster API — инструмент для предоставления удаленного доступа к услугам другим пользователям, например системным администраторам. Ранее мы рассказали, как запускать hoster API и управлять ключами. Для настройки доступа в hoster API, помимо ключей, используются и токены — средства идентификации пользователя.

Откройте hoster API. В интерфейсе доступны запросы для управления сервисами, а также возможные ответы на них со статус-кодами и описаниями. Перечень запросов можно скачать в формате .json-файла.

Запросы объединены в группы в навигационной панели слева. Нажмите на название группы, чтобы открыть список включенных в нее запросов. 

Создание токенов 

После создания ключей нужно получить токены access token и refresh token, а также идентификатор пользователя — userID.

1. Для этого в навигационной панели откройте группу ServiceAccount и выберите запрос Create service-account tokens. Затем скопируйте URL для создания токенов.

2. Откройте приложение для выполнения HTTP-запросов (например, Postman), вставьте URL назначения в строку запроса и установите метод запроса. 

3. На вкладке «Headers» добавьте в список данные ключей Access Key и Secret Key.  

4. Нажмите «Send» и выполните запрос.

Если запрос выполнен успешно (статус 200 OK), вы получите ответ со следующими данными:

• access token — хеш-строка (JWT) с данными о пользователе (ID) и перечне доступных ему действий (данные поступают из ключей сервисного аккаунта). Необходим для получения доступа к сервисам. 
• refresh token — хеш-строка с данными из ключей сервисного аккаунта, необходимыми для обновления пары токенов. Максимальный срок их действия ограничен сроком действия ключей сервис-аккаунта.
• userID — цифровой индикатор пользователя в наших сервисах. 
• dateExpires — дата истечения срока действия access token в формате timestamp.

Эти данные можно использовать в запросах на управление услугами. Перечень запросов представлен на странице API-документации на вкладке соответствующего сервиса. 

Обновление токенов

Если срок действия access token истек, необходимо выполнить запрос на обновление обоих токенов с использованием хеша refresh token в заголовке. Произойдет проверка срока действия refresh token, по результатам которой: 

• если срок refresh token не истек, будут заново созданы оба токена; 
• если срок refresh token истек, нужно снова направить запрос на создание токенов.

Для обновления токенов необходимо к URL назначения (https://serviceapi.hoster.by) направить запрос «…/token/refresh» и передать в заголовках refresh-Token и Х-User-Id (отображается при создании токенов как userID).

Просмотр информации о токенах

Для просмотра информации о токенах необходимо к URL назначения (https://serviceapi.hoster.by) направить запрос: 

• для access token — «.../token/info/access» (см. скрин. ниже) 
• для refresh token — «…/token/info/refresh»