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-метод великими літерами, шлях із query string, 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 може змінитися після нового запуску. Для цих маршрутів потрібне право «Читання» потоку, а кожна адреса й сторінка підписуються окремо.