Ключі API

Ключі API відкривають програмний доступ до dAio Business. Вони дозволяють вашим власним застосункам, скриптам і системам напряму звертатися до платформи — погода, якість повітря, пилок, морські умови, галузева аналітика — без використання вебінтерфейсу. Це точка входу для індустріалізації ваших інтеграцій: живлення ERP, запуск бізнес-процесу, відображення прогнозів у вашій власній інформаційній панелі.

Кожен ключ автентифікує виклики від імені вашої організації та успадковує її права. У поєднанні з вебхуками він дає вам повний канал: ви звертаєтесь до dAio на вимогу через API, а dAio сповіщає вас у реальному часі через вебхуки.

Порада: створюйте окремий ключ для кожного використання (служба, середовище, партнер). Ви зможете відкликати один, не перериваючи інші, та точно відстежувати, яка інтеграція що споживає.

Для чого потрібен ключ API

Потреба	Ключ API дозволяє…
Інтеграція	Підключити dAio до вашої інформаційної системи (ERP, CMMS, BI) без втручання людини.
Автоматизація	Запускати заплановані обробки (щоденне отримання прогнозів, оцінювання ризиків).
Розповсюдження	Відображати дані dAio у ваших власних застосунках або порталах.
Контрольований спільний доступ	Надати партнеру обмежений і відкличний доступ без створення облікового запису користувача.

Інформація: доступ до API зарезервовано для платних планів. Організація без активної підписки отримує відповідь 403 (« API access requires a paid plan ») на кожен виклик.

Створення ключа

Створення ключа зарезервовано за власником (owner) та адміністраторами (admin) організації. Інші ролі не можуть ані створювати, ані відкликати ключі.

1. Перейдіть до Налаштування > Ключі API.
2. Натисніть Новий ключ угорі праворуч.
3. Введіть описову назву, що ідентифікує використання ключа (напр. « Бекенд продакшну », « Конектор Power BI », « Інтеграція партнера X »).
4. Натисніть Створити.
5. Повний ключ відображається в зеленому банері: негайно скопіюйте його за допомогою кнопки копіювання.

Увага: повний ключ відображається лише один раз, у момент його створення. Згодом він ніколи не відображається повторно — платформа зберігає лише зашифрований відбиток. Якщо ви його втратите, доведеться згенерувати новий. Без зволікання збережіть його в менеджері секретів (Vault, AWS Secrets Manager, зашифровані змінні середовища).

Після створення ключ з'являється у списку зі своєю назвою, своїм префіксом (перші символи, щоб ідентифікувати його без розкриття), індикатором стану (зелений = активний, червоний = відкликаний) та своєю датою останнього використання.

Використання ключа

Усі запити до API dAio повинні містити ваш ключ у HTTP-заголовку X-API-Key. Базовою адресою API є https://api-dev.daio.app, а точки доступу B2B мають префікс /api/v1/.

curl -H "X-API-Key: VASH_KLYUCH_API" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

Увага: очікуваним заголовком є саме X-API-Key, а не Authorization: Bearer. Недійсний, відкликаний або переданий в іншому заголовку ключ повертає відповідь 401 (« Invalid API key »).

Зверніться до технічної документації API для повного переліку точок доступу (погода, погодинні прогнози, якість повітря, пилок, морські дані, пакетна обробка) та формату відповідей.

Обмеження частоти

Для гарантування стабільності сервісу кожен ключ підлягає погодинному обмеженню частоти. Лічильник є власним для кожного ключа та скидається щогодини.

План	Запитів на годину
Безкоштовний / без підписки	Жодного доступу до API
Solo · Team · Enterprise (dAio Business)	20 000

Коли ліміт досягнуто, API повертає відповідь 429 (« Rate limit exceeded ») разом із заголовком Retry-After, що вказує час очікування до повторної спроби.

Інформація: це погодинне обмеження відрізняється від місячної квоти запитів, включеної до вашого тарифу. Перегляньте деталі квот за планами в розділі Підписка.

Ротація ключа

Ротація перегенеровує ключ, зберігаючи його назву та позицію у списку. Використовуйте її для періодичного оновлення своїх секретів без переналаштування всієї вашої інтеграції.

1. У списку натисніть піктограму ротації (кругова стрілка) навпроти ключа.
2. Підтвердіть операцію.
3. Нове значення відображається лише один раз — негайно скопіюйте його.
4. Оновіть свої застосунки цим новим значенням.

Порада: плануйте ротацію кожні 90 днів і систематично після звільнення співробітника, який мав доступ до секретів, або в разі підозри на витік.

Відкликання ключа

Щоб перервати доступ скомпрометованого або невикористовуваного ключа:

1. У списку натисніть піктограму видалення (кошик) навпроти ключа.
2. Підтвердіть відкликання.

Відкликання є негайним і незворотним. Будь-який запит, що використовує відкликаний ключ, одразу отримає відповідь 401. Ключ залишається видимим у списку, позначений як Відкликаний, для історії.

Безпека ключів

Ключ API дорівнює паролю: будь-хто, хто ним володіє, може звертатися до API з правами вашої організації.

Увага: ніколи не комітьте ключ у ваш вихідний код чи репозиторій Git, навіть приватний. Ключ, помилково відправлений до репозиторію, вважається скомпрометованим — відкличте його та виконайте ротацію без зволікання. Ніколи не передавайте його електронною поштою, у месенджері чи в тикеті підтримки у відкритому вигляді.

• Зберігайте ключі в менеджері секретів або у змінних середовища, ніколи жорстко не прописуйте в коді.
• Не розкривайте їх на стороні клієнта (вебзастосунок, мобільний, браузерний JavaScript): виклик API повинен виходити з вашого сервера.
• Розмежовуйте: один ключ на середовище (продакшн, тестування) і на використання.
• Відстежуйте дату останнього використання: ключ, давно неактивний, — це ключ, який слід відкликати.

Найкращі практики

• Називайте явно кожен ключ відповідно до його використання та середовища, щоб з першого погляду визначити, що він живить.
• Застосовуйте найменші привілеї: створюйте виділені та відкличні ключі замість єдиного ключа, спільного для всіх ваших інтеграцій.
• Автоматизуйте ротацію кожні 90 днів та інтегруйте її у ваші процедури звільнення співробітників.
• Обробляйте 429 на стороні клієнта: дотримуйтесь заголовка Retry-After і згладжуйте свої виклики замість того, щоб надсилати запити поспіль.
• Негайно відкликайте будь-який ключ, щодо якого є підозра в компрометації — відкликання набирає чинності без зволікання.
• Документуйте внутрішньо, який ключ для чого слугує і хто за нього відповідає, для спокійних аудитів безпеки.

Порада: поєднуйте ваші ключі API з вебхуками для повної інтеграції — звертайтеся до dAio на вимогу та дозвольте dAio сповіщати вас про події в реальному часі.