API-ключи

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

Каждый ключ аутентифицирует вызовы от имени вашей организации и наследует её права. В сочетании с вебхуками он даёт вам полноценный канал: вы запрашиваете dAio по требованию через API, а dAio уведомляет вас в реальном времени через вебхуки.

Совет: создавайте отдельный ключ для каждого случая использования (сервис, среда, партнёр). Вы сможете отозвать один, не прерывая остальные, и точно отслеживать, какая интеграция что потребляет.

Для чего нужен API-ключ

Потребность	API-ключ позволяет…
Интеграция	Подключить dAio к вашей информационной системе (ERP, EAM, BI) без участия человека.
Автоматизация	Запускать запланированные процессы (ежедневное получение прогнозов, скоринг рисков).
Распространение	Отображать данные dAio в ваших собственных приложениях или порталах.
Контролируемый обмен	Предоставить партнёру ограниченный и отзываемый доступ без создания учётной записи пользователя.

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

Создание ключа

Создание ключа доступно только владельцу (owner) и администраторам (admin) организации. Остальные роли не могут создавать или отзывать ключи.

1. Перейдите в раздел Настройки > API-ключи.
2. Нажмите Новый ключ в правом верхнем углу.
3. Введите описательное имя, обозначающее назначение ключа (напр. « Backend production », « Коннектор 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: VOTRE_CLE_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 должен исходить с вашего сервера.
• Разделяйте: один ключ на каждую среду (production, тестовая) и на каждое использование.
• Следите за датой последнего использования: ключ, давно неактивный, — это ключ, подлежащий отзыву.

Рекомендации

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

Совет: свяжите ваши API-ключи с вебхуками для полноценной интеграции — запрашивайте dAio по требованию и позвольте dAio уведомлять вас о событиях в реальном времени.