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

Обновлено

Этот сценарий выполняет первый read-only запрос. Для него достаточно scope cabinet:read.

Создайте ключ в настройках External API в Alitos. Значение показывается один раз. Не передавайте его напрямую в resource endpoints.

1. Обменяйте ключ на 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": "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 в переменную ALITOS_EXTERNAL_JWT. JWT действует 60 минут. Получайте новый JWT до истечения срока, но не сохраняйте его на диск.

2. Проверьте возможности

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

Ответ содержит effective scopes, режим доступа к кабинетам, rollout-возможности и актуальные лимиты.

{
  "contractVersion": "2026-08-09.5",
  "resource": "https://api.alitos.io/v1/external",
  "actorUserId": "9480c5c0-c1f2-4d61-8a15-f2ac5d0a67db",
  "credentialId": "42",
  "scopes": ["cabinet:read"],
  "cabinetAccess": {
    "mode": "all_current",
    "cabinetIds": []
  },
  "features": {
    "readsEnabled": true,
    "writesEnabled": true,
    "projectWritesEnabled": true,
    "settingsWritesEnabled": true,
    "sensitiveDataAndExportsEnabled": true
  },
  "limits": {
    "readRequestsPerMinute": 60,
    "postRequestsPerMinute": 15,
    "maxConcurrentOperations": 2,
    "operationRetentionDays": 7,
    "maxRequestBodyBytes": 1048576
  },
  "permissionCatalogVersion": 1
}

Ответ может содержать дополнительные поля. Не сравнивайте JSON как строку.

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

curl 'https://api.alitos.io/v1/external/cabinets?limit=20' \
  --header "Authorization: Bearer ${ALITOS_EXTERNAL_JWT}"
{
  "items": [
    {
      "kind": "cabinet",
      "cabinetId": "123456789",
      "login": "example-login",
      "name": "Пример кабинета"
    }
  ],
  "nextCursor": null
}

Значения в примере фиктивные. Используйте cabinetId, возвращенный вашей интеграции. Не преобразуйте его в JavaScript number.

Что дальше

  • Для создания проектов используйте cabinet:projects:write.

  • Для обработки фоновых задач прочитайте правила операций.

  • Полные схемы доступны в OpenAPI.