API-ключи

Зачем это нужно

API-ключ позволяет программе — десктопному клиенту (Arbogeo, Арборитм), скрипту или интеграции — обращаться к API платформы от имени вашего аккаунта, без входа через браузер.

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

Кому доступны ключи

API-ключи доступны аккаунтам с доступом к платформе — тем же, кто видит проекты и обработку в кабинете. Доступ выдаёт администратор; администраторы и владельцы имеют его всегда.

Проверка выполняется на каждом запросе, а не только при создании ключа: если доступ к платформе отключат, все выданные ключи сразу перестанут работать и вернут 403. Список ключей и кнопка отзыва при этом остаются доступны, чтобы можно было прибраться.

API-ключ — это не лицензия. Лицензионный ключ активирует десктопный Арборитм на конкретном устройстве; API-ключ — это учётные данные для обращений к API.

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

1. Откройте Настройки аккаунта → Безопасность → API-ключи.
2. Нажмите Создать.
3. Укажите название — по нему вы потом поймёте, какой ключ где используется («Arbogeo, рабочий ноутбук»).
4. При необходимости включите Только чтение. Администраторы могут также выбрать назначение ключа — см. «Права ключа».
5. Нажмите Создать ключ.

Ключ выглядит так:

arbo_3f9a1c07_qJ8x2mN4pR7tV1wY6zB0dK5hL3sG9fA2cE8uI4oP

Видимая часть (arbo_3f9a1c07_…) остаётся в списке ключей — по ней вы опознаёте ключ и отзываете нужный.

Использование

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

curl -H "Authorization: Bearer arbo_3f9a1c07_qJ8x2mN4pR7t…" \
  https://arboritm.ru/api/v1/projects/

Пример на Python:

import httpx

client = httpx.Client(
    base_url="https://arboritm.ru/api/v1",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
projects = client.get("/projects/").json()

Полный перечень методов и схем — в интерактивной OpenAPI-документации: https://arboritm.ru/api/v1/docs.

Права ключа

Чего ключ не может независимо от режима:

• управлять ключами — эндпоинты /api/v1/account/** закрыты для ключей, создать или отозвать ключ можно только после входа в кабинет;
• обращаться к админским разделам (/api/v1/admin/**) и эндпоинтам авторизации (/api/v1/auth/**), даже если аккаунт администраторский;
• подключаться к WebSocket — для реалтайма используется вход в кабинет.

Это ограничивает ущерб от утечки ключа: им нельзя ни расширить себе доступ, ни удалить аккаунт.

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

• «Чтение тикетов поддержки» — только чтение обращений в поддержку: список, счётчики и переписка. Ответить клиенту, сменить статус или открыть другие разделы через него нельзя.
• «Администрирование продуктов» — при создании выбираются одна или обе области; они могут быть в одном ключе.
  • «Карточки релизов» — посмотреть список продуктов и релизов, изменить карточку релиза (описание изменений, канал, статус публикации, пометку «последний», активность) и карточку продукта (название, описание, ссылку и инструкции по установке). Загрузить или удалить файл релиза, сменить иконку и режим доступа продукта, создать продукт, обработать заявки на доступ через такой ключ нельзя.
  • «Аналитика» — только чтение: скачивания и версии по продуктам, использование приложений и нагрузка воркеров. События отдельных скачиваний, сброс статистики и остальные админские разделы остаются закрытыми.

Срок жизни, лимиты, отзыв

• Срок жизни — по умолчанию бессрочный, чтобы десктопный клиент не отвалился молча. Ограничить срок можно при создании через API (expires_at).
• Лимит — до 20 активных ключей на аккаунт. Выдавайте отдельный ключ на каждое устройство: тогда потерянный ноутбук отзывается без остановки остальных.
• Отзыв — кнопка «Отозвать» в списке ключей. Действует немедленно, следующий запрос с этим ключом получит 401.
• Ограничение частоты запросов считается по самому ключу, а не по IP-адресу. Несколько клиентов из одной сети не мешают друг другу.

Создание и отзыв ключа попадают в Журнал безопасности аккаунта. Администратор платформы также может отозвать любой ключ — в этом случае запись в журнале появится с пометкой о действии администратора.

Коды ошибок

Если ключ утёк

1. Отзовите ключ в Настройки аккаунта → Безопасность → API-ключи.
2. Создайте новый и пропишите его в клиенте.
3. Проверьте Журнал безопасности — там видно время последнего использования каждого ключа.