К содержимому

Быстрый старт

Обновлено

Получите JWT и список доступных кабинетов. Этот сценарий только читает данные; достаточно scope cabinet:read.

1. Создайте ключ доступа

Понадобятся пользователь Alitos с правом external_api_access и доступом хотя бы к одному кабинету, Bash и curl. В Alitos откройте раздел «Доступ к Alitos API» и нажмите «Создать токен». Выберите право cabinet:read и нужные кабинеты. Эта кнопка создаёт ключ доступа вида alitos_cred_...; JWT получите следующим шагом.

Полное значение ключа показывается один раз. Сохраните его в хранилище секретов. Если ответ создания потерян, не повторяйте создание автоматически: обновите список ключей и отзовите ключ, секрет которого недоступен. Подробнее — ключи доступа и авторизация.

Для выполнения примера введите ключ в Bash; ввод скрыт и не попадёт в историю команд:

read -r -s -p 'Ключ доступа: ' ALITOS_EXTERNAL_CREDENTIAL
printf '\n'

В приложении загружайте эту переменную из хранилища секретов. Не передавайте сам ключ в запросы /v1/external.

2. Обменяйте ключ на JWT

curl --request POST 'https://api.alitos.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:alitos:params:oauth:token-type:external-access-credential' \
  --data-urlencode "subject_token=${ALITOS_EXTERNAL_CREDENTIAL}" \
  --data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'resource=https://api.alitos.io/v1/external' \
  --data-urlencode 'scope=cabinet:read'

Успешный ответ; значение access_token в примере сокращено:

{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "cabinet:read",
  "resource": "https://api.alitos.io/v1/external"
}

Скопируйте полное значение access_token из вашего ответа и введите его:

read -r -s -p 'access_token: ' ALITOS_EXTERNAL_JWT
printf '\n'

JWT действует 60 минут. Refresh token не выдаётся: приложение получает новый JWT повторным обменом до истечения срока и хранит его только в памяти процесса. Не сохраняйте ответ обмена в логи или на диск.

3. Проверьте доступность API

curl 'https://api.alitos.io/v1/external/capabilities' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Убедитесь, что scopes содержит cabinet:read, а features.readsEnabled равно true. Поля features показывают доступность групп API, а не права на кабинет. Используйте текущие limits для ограничения частоты запросов. Ответ может содержать дополнительные поля — игнорируйте неизвестные.

4. Найдите кабинет

curl 'https://api.alitos.io/v1/external/cabinets?limit=20' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"

Выберите кабинет из items и сохраните его cabinetId. Это строка с точным 64-битным идентификатором: не преобразуйте её в JavaScript number.

Если пришёл непустой nextCursor, передайте его без изменений как параметр cursor следующего GET-запроса, сохранив фильтры. Пустой список означает, что запрос не вернул доступных кабинетов; проверьте ограничения ключа и права пользователя.

Что дальше

Если у ключа нет нужного scope, выпустите новый: права существующего ключа неизменяемы. Затем обменяйте новый ключ на JWT с нужными scopes. Изменение одного поля scope при обмене не расширяет права ключа.

Полные схемы запросов и ответов — в OpenAPI.