API-ключи

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

Принцип работы

[Ваше приложение]
    | Authorization: Bearer bp_live_a3f8...5e82
    v
https://beepass.io/api/v1/queens
    | SHA-256 валидация -> поиск в БД -> проверка разрешений
    v
[JSON-данные в ответе]

1. Создайте ключ через веб-интерфейс (меню аватара -> API-ключи)
2. Скопируйте ключ -- он будет показан только один раз
3. Используйте его в заголовке Authorization ваших запросов

Формат ключа

bp_live_ + 64 шестнадцатеричных символа = 72 символа

Пример: bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Безопасность

Исходный ключ отображается только один раз при создании. BeePass хранит только SHA-256 хеш -- восстановить потерянный ключ невозможно. Вам потребуется создать новый.

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

Добавьте ключ в заголовок Authorization каждого запроса:

curl -H "Authorization: Bearer bp_live_a3f8..." \
     https://beepass.io/api/v1/queens

const response = await fetch('https://beepass.io/api/v1/queens', {
  headers: {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
}
response = requests.get('https://beepass.io/api/v1/queens', headers=headers)
data = response.json()

Разрешения

Каждый ключ определяет уровень доступа для каждого ресурса:

Ресурс	Описание
Queens	Матки F0 и F1 (племенное поголовье, продуктивные)
Evaluations	Оценки продуктивности
BLUP	Расчётные племенные ценности (EBV)
Hive	Пасеки и ульи
Account	Профиль и настройки учётной записи

Уровни разрешений

Уровень	Чтение (GET)	Запись (POST/PUT/DELETE)
None	-	-
Read	Да	-
Write	Да	Да

совет

Уровень Write автоматически включает доступ на чтение. Устанавливать оба уровня не требуется.

Шаблоны предустановок

Шаблон	Описание	Разрешения
Только чтение	Просмотр всех данных	Все ресурсы в режиме чтения
Оценщик	Ввод полевых оценок	Оценки на запись, остальное на чтение (кроме Hive)
Пользовательский	Ручная настройка	Вы выбираете каждое разрешение

Ограничения

Срок действия (TTL)

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

Вариант	Описание
7 дней	Тестирование и разработка
30 дней	Временные интеграции
90 дней	Стандартное использование
365 дней	Долгосрочные интеграции
Без ограничений	Без автоматического истечения

Просроченный ключ автоматически отклоняется. Он остаётся видимым в списке со статусом «Истёк».

Ограничение по IP

Ограничьте использование ключа определёнными IP-адресами для повышения безопасности:

• Один IP: 203.0.113.5
• Подсеть CIDR: 192.168.1.0/24

Если IP не указан, ключ может использоваться с любого адреса.

информация

Ограничение по IP проверяется при каждом запросе. IP-адрес клиента извлекается из заголовков CF-Connecting-IP, X-Forwarded-For или X-Real-IP.

Управление ключами

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

Перейдите на страницу API-ключи через меню аватара в заголовке, затем нажмите Сгенерировать ключ. Мастер из 4 шагов проведёт вас:

1. Имя — выберите описательное имя и шаблон разрешений
2. Разрешения — настройте разрешения для каждого ресурса (пользовательский режим)
3. Ограничения — установите срок действия и разрешённые IP-адреса
4. Сгенерированный ключ — немедленно скопируйте ваш ключ

Отключение / Повторное включение

Используйте переключатель в столбце «Активен» для временного отключения ключа без его удаления. Отключённый ключ немедленно отклоняется API.

Отзыв

Нажмите на значок корзины, затем подтвердите отзыв. Ключ переходит в статус «Отозван» и не может быть повторно активирован.

Лимиты

Лимит	Значение
Макс. ключей на пользователя	20
Создание в час	10
Длина имени	от 1 до 100 символов

API управления

Ключи управляются через стандартный REST API (аутентификация сессии Supabase):

Метод	Маршрут	Описание
GET	/api/api-keys	Список ваших ключей (без хеша)
POST	/api/api-keys	Создание нового ключа
PUT	/api/api-keys/{id}	Обновление имени или статуса
DELETE	/api/api-keys	Отзыв ключа

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

curl -X POST https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{
    "name": "My mobile app",
    "permissions": {
      "queens": "read",
      "evaluations": "write",
      "blup": "read",
      "hive": "none",
      "account": "read"
    },
    "expires_in_days": 90,
    "ip_allowlist": ["203.0.113.0/24"]
  }'

Ответ (201):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
    "key_prefix": "bp_live_a3f8e2b1...f0a1"
  }
}

Отзыв ключа (DELETE)

curl -X DELETE https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{ "id": "550e8400-e29b-41d4-a716-446655440000" }'

Коды ошибок

Код	Ситуация
400	Некорректные параметры (имя, разрешения, TTL, IP)
400	Достигнут максимум в 20 ключей
401	Неаутентифицированная сессия
429	Превышен лимит создания (10/ч)

---

См. также: Обзор | Аутентификация | Матки | Оценки