Аутентификация и API-ключи

Каждый запрос к API передаёт API-ключ организации в заголовке X-API-Key. Ключ принадлежит одной организации AgroSat и даёт доступ только к полям, которые эта организация зарегистрировала через API.

Как получить доступ

Доступ к API предоставляется по договору с AgroSat. Когда AgroSat включает API для вашей организации, её владелец может создавать ключи. Самостоятельной регистрации нет.

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

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

Раздел API и создание ключей доступны только владельцу организации.

1. Войдите в веб-приложение AgroSat на app.agrosat.uz и откройте Настройки.

2. В карточке API-ключи введите название, по которому будет понятно, где используется ключ, например production или staging, и нажмите Создать.

3. Сразу скопируйте ключ. Он начинается с ags_ и показывается только один раз: AgroSat хранит лишь его префикс и хеш.

4. Сохраните ключ в менеджере секретов или в окружении развёртывания, но не в исходном коде.

В карточке видны все ключи: название, префикс, кто создал ключ, когда и с какого IP-адреса, когда он последний раз использовался и когда истекает. Число действующих ключей ограничено договором (по умолчанию 2). Когда лимит достигнут, отзовите один ключ, прежде чем создать новый.

Передача ключа

Передавайте ключ в заголовке X-API-Key в каждом запросе.

curl

curl https://api.agrosat.uz/v1/fields -H "X-API-Key: $AGROSAT_API_KEY"

Python

import os
import requests

session = requests.Session()
session.headers["X-API-Key"] = os.environ["AGROSAT_API_KEY"]
r = session.get("https://api.agrosat.uz/v1/fields", timeout=30)

JavaScript

const res = await fetch("https://api.agrosat.uz/v1/fields", {
  headers: { "X-API-Key": process.env.AGROSAT_API_KEY },
});

Только в заголовке

Ключ в строке запроса, например ?api_key=…, не принимается: запрос завершится ошибкой 401 invalid_api_key. Строки запросов попадают в журналы и историю браузера.

Запрос получает 401 invalid_api_key, если ключ не передан, неизвестен, отозван или истёк, а также если доступ к API для организации выключен или срок её договора закончился.

Замена ключа

Чтобы ничего не сломалось, на время замены используйте оба ключа:

1. Создайте новый ключ в разделе Настройки → API-ключи.

2. Разверните его во всех сервисах, которые обращаются к API.

3. Отзовите старый ключ. Начиная со следующего запроса он будет получать 401.

Если лимит ключей уже исчерпан, сначала отзовите неиспользуемый ключ или попросите AgroSat увеличить лимит.

Отзыв ключа

Нажмите значок отзыва рядом с ключом в разделе Настройки → API-ключи и подтвердите действие. Ключ сразу перестаёт работать, восстановить его нельзя. Отзывайте ключ, как только заподозрите утечку.

Храните ключи на сервере

API предназначен для обмена между серверами. Браузеры могут обращаться к нему только со страниц https://docs.agrosat.uz, запросы с других веб-источников браузер заблокирует. Никогда не встраивайте ключ в веб-страницу, мобильное приложение или публичный репозиторий: любой, кто его извлечёт, сможет тратить ваши юниты и гектары.

Что дальше

Регистрация полейПередача границ полей и управление ими.

Лимиты частотыСколько запросов в минуту может отправлять ключ.

Использование в порталеЮниты, гектары и ключи в веб-приложении.