1. Назначьте владельца интеграции

Откройте «Настройки → Доступ → API-клиенты» как администратор. Создайте отдельного клиента для каждой внешней системы и среды: так можно заменить ключ или отключить один канал, не останавливая остальные. Введите понятное название и пользователя-владельца. Ключ действует только в пределах его прав.

Выберите «Запись» для приёма данных и «Чтение» для статусов, результатов и точек выдачи. Запись доступна лишь для потоков, которые владелец может запускать; чтение — которые он видит. Выдача с запуском по запросу также требует права запуска у владельца. Отключение владельца или удаление его прав немедленно влияет на ключ.

2. Ограничьте срок, сеть и нагрузку

Выберите дату окончания — до конца указанного дня UTC, не более чем через три года. Добавьте разрешённые IPv4/IPv6-адреса или сети CIDR, по одной в строке. IP-доступ и HMAC независимы: «Любые IP-адреса» отключает IP-фильтрацию. Подпись включена по умолчанию; рекомендуется сохранять её, особенно без IP-ограничений. Задайте запросы в минуту. Одновременно действует общий лимит API раздела.

Сохраните клиента и передайте созданный ключ по защищённому каналу. Не помещайте его в код браузера, публичный репозиторий или URL. Data Bridge генерирует ключ; произвольные собственные ключи не поддерживаются. Показ полного ключа записывается в аудит. Для примеров и тестов используйте переменную окружения.

3. Подпишите точный HTTP-запрос

Передавайте ключ в Authorization: Bearer ... или X-API-Key. HMAC дополнительно требует X-UBC-Timestamp с секундами Unix и X-UBC-Signature: v1=<hex>. Вычислите HMAC-SHA256 ключом клиента по четырём значениям, разделённым переводами строк: время, HTTP-метод заглавными буквами, путь со строкой запроса и шестнадцатеричный SHA-256 точных байтов тела.

Расхождение часов с сервером не должно превышать пяти минут. Сохраняйте порядок параметров, кодирование и префикс установки. Не меняйте тело после подписи: JSON с другим оформлением имеет другой хеш. Для GET хешируйте пустые байты. Секрет — ключ API-клиента, а не секрет обратного вызова.

4. Проверьте доступ через ping

В среде Python с установленным requests задайте UBC_API_KEY и UBC_API_PING_URL. Вторая переменная — полный HTTPS-адрес /api/v1/pingс нужным префиксом. Пример подготавливает запрос до подписи, поэтому использует фактический закодированный путь; перенаправления отключены.

import hashlib, hmac, os, time
from urllib.parse import urlsplit
import requests

key = os.environ["UBC_API_KEY"]
url = os.environ["UBC_API_PING_URL"]
request = requests.Request("GET", url).prepare()
body = request.body or b""
if isinstance(body, str):
    body = body.encode("utf-8")
parts = urlsplit(request.url)
path = parts.path + ("?" + parts.query if parts.query else "")
timestamp = str(int(time.time()))
canonical = "\n".join([
    timestamp, request.method, path,
    hashlib.sha256(body).hexdigest()
])
signature = hmac.new(key.encode("utf-8"),
                     canonical.encode("utf-8"),
                     hashlib.sha256).hexdigest()
request.headers.update({
    "Authorization": "Bearer " + key,
    "X-UBC-Timestamp": timestamp,
    "X-UBC-Signature": "v1=" + signature,
})
with requests.Session() as session:
    response = session.send(request, timeout=30,
                            allow_redirects=False)
    print(response.status_code, response.text)

Проверьте возвращённого клиента, время сервера, срок действия и права. Затем вызовите GET /api/v1/flows и убедитесь, что доступны только согласованные потоки. Изменение адреса требует новой подписи. Для POST подготовьте тело один раз, подпишите его байты и отправьте именно их.

5. Повторы, смена ключа и диагностика

Подпись принимается один раз: повтор возвращает 409 API_SIGNATURE_REPLAY. Заново подписывайте каждое опрашивание или повтор доставки; соблюдайте Retry-After , чтобы не повторить одинаковый GET в ту же секунду. Сохраняйте для доставки Idempotency-Key: он предотвращает повторное выполнение, а HMAC защищает отдельный HTTP-запрос.

401 обычно связан с ключом, сроком действия или подписью; 403— с IP или правами; 429— с частотой запросов. Изучите точный код ответа и запись аудита. Повторные ошибки аутентификации временно блокируют IP-адрес.

Для смены ключа администратор создаёт новый и сохраняет клиента: прежний перестаёт работать. В «API → Мои API-ключи», если роль разрешает, владельцы могут просматривать и обновлять ключи; самостоятельная замена действует сразу. После замены проверьте ping и один разрешённый сценарий, затем удалите старый секрет из внешней системы.

Для управляемого доступа к истории используйте GET /api/v1/flows/{flow}/runs. Список результатов завершённого запуска доступен по /api/v1/flows/{flow}/results?run=latest; конкретная таблица — по /api/v1/flows/{flow}/results/{block}?format=json&offset=0&limit=100. Берите идентификаторы из ответа, а не чужого примера. При чтении нескольких таблиц одного результата фиксируйте конкретный run: latest может измениться после нового выполнения. Маршруты требуют «Чтения» потока; при включённой подписи каждый адрес и каждая страница подписываются отдельно.