Аутентификация

Формат API-ключа

Для серверной интеграции с API обработки документов используйте API-ключ. Ключ имеет формат:

sk_konergy_{publicId}_{secret}

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

Заголовок Authorization

Передавайте ключ в HTTP-заголовке Authorization:

Authorization: Bearer sk_konergy_aBcD1234_your32charsecretkeyherexxxxxxxx

Передавайте секрет только по HTTPS и только с вашего сервера. Не помещайте его в адрес запроса, браузерный код или логи. Неверный, истёкший или отозванный ключ возвращает 401 UNAUTHORIZED.

Проверка ключа и права доступа

Выполните GET /api/auth/verify на https://platform-api.konergy.ru с вашим ключом. Проверка бесплатная и не требует пополненного кошелька. Ответ 200 содержит только идентификатор ключа, владельца, workspace и срок действия. Секрет, баланс и персональные данные не возвращаются.

curl https://platform-api.konergy.ru/api/auth/verify \
  -H "Authorization: Bearer $KONERGY_API_KEY"

Статус «Активен» означает, что ключ действителен, а не что ему доступны все операции. Для доступа к документам дополнительно проверяются владелец, workspace и доступность ресурса через API; обработка документа также зависит от средств и лимитов. Настраиваемых разрешений для отдельных ключей пока нет.

Валидный ключ на маршруте, требующем входа пользователя, получает 403 FORBIDDEN. В частности, GET /billing/me/summary не является проверкой API-ключа. Для настроек аккаунта используйте личный кабинет. Management API требует пользовательский JWT, а не sk_konergy_....

«Последнее использование» отмечает успешную проверку подлинности ключа, включая этот запрос; обновление может появиться с небольшой задержкой. Это не подтверждение успешной обработки документа или списания средств.

Типы ключей

Персональные ключи

Привязаны к вашему аккаунту. Все расходы списываются с вашего личного кошелька.

• Максимум 10 активных ключей на пользователя
• Создание и отзыв — в личном кабинете. Для авторизованного пользователя Management API: POST /billing/api-keys/personal, POST /billing/api-keys/personal/:id/revoke.

Ключи организации

Привязаны к организации. Расходы списываются с кошелька организации. Могут быть ограничены ежемесячным лимитом расходов (spend limit).

• Максимум 50 активных ключей на организацию
• Создать ключ могут только owner и admin
• Ключ можно привязать к workspace организации через поле workspaceId
• Управление после входа владельца или администратора: POST /billing/organizations/:orgId/api-keys, POST /billing/organizations/:orgId/api-keys/:id/revoke.

Жизненный цикл ключа

1. Создание — ключ генерируется, секретная часть показывается один раз
2. Использование — передавайте ключ в каждом запросе через заголовок Authorization
3. Ротация — создайте новый ключ, обновите все интеграции, отзовите старый
4. Отзыв — отзовите ключ в личном кабинете. Новые запросы с отозванным ключом отклоняются; это не отменяет уже принятые задания.

Рекомендации по безопасности

• Никогда не коммитьте ключи в систему контроля версий
• Используйте переменные окружения: KONERGY_API_KEY=sk_konergy_...
• Регулярно ротируйте ключи — создавайте новый, переключайте интеграции, отзывайте старый
• Используйте разные ключи для разных сред (dev, staging, production)
• Для организаций устанавливайте лимиты расходов, чтобы контролировать бюджет
• Отзывайте неиспользуемые ключи

Общие заголовки запросов