⚡️ API-ключи.

Что такое API-ключ и зачем он нужен

API-ключ — это уникальная строка, которая позволяет сторонним приложениям или скриптам обращаться к данным вашего аккаунта на Headframe и совершать действия от его имени — без ручного входа через браузер.

Раньше ключи выдавались только через обращение в поддержку. Теперь вы можете создавать и управлять ими самостоятельно прямо в личном кабинете — с полным контролем над тем, кому и к чему дать доступ.

Типичные сценарии использования:

• Автоматизация мониторинга хешрейта и воркеров
• Интеграция с внешними дашбордами и системами аналитики
• Управление аккаунтами клиентов из собственного интерфейса
• Работа с несколькими аккаунтами через единый скрипт

Уровни доступа

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

Наблюдатель – только чтение: просмотр статистики, воркеров, хешрейта.
Бухгалтер – просмотр финансовой информации: начисления, выплаты.
Казначей – доступ к финансовым операциям хаба, включая данные по майнерам.
Администратор – полный доступ: управление настройками, воркерами, клиентами.

Принцип минимального доступа
Давайте ключу ровно столько прав, сколько нужно для конкретной задачи. Если интеграция только читает статистику — выбирайте «Наблюдатель», а не «Администратор».

Область доступа (скоуп)

Помимо уровня прав, вы выбираете, к каким именно сущностям будет применяться ключ: майнерам, операторам (хабам) или пулам.

Вы видите только те сущности, которые доступны вашему аккаунту. Если у вас нет операторов — этот раздел просто не отобразится.

«Выбрать все» — что это значит

Если поставить галочку «Выбрать все», ключ будет автоматически распространяться на все текущие и будущие сущности. Например, если вы позже добавите нового майнера — ключ автоматически получит к нему доступ.

Если выбрать сущности вручную — ключ будет работать только для тех, что указаны при создании. Новые сущности к нему не добавятся автоматически.

Как создать ключ

Раздел находится по пути: Аккаунт → Доступы → API-ключи.

1. Введите название ключа — это обязательное поле. Название помогает понять, для чего ключ создан (например:  monitoring-bot ,  dashboard-readonly ).
2. Выберите уровень доступа из выпадающего списка.
3. Отметьте сущности, к которым будет применяться ключ, или нажмите «Выбрать все».
4. Нажмите «Создать ключ» и подтвердите действие через двухфакторную аутентификацию.
5. Скопируйте и сохраните ключ. Он показывается только один раз — полностью. После закрытия окна восстановить его невозможно.

⚠️ Ключ показывается только один раз
После создания ключ отображается целиком лишь в момент генерации. Сохраните его в надёжном месте: менеджере паролей, переменных окружения или секретах CI/CD. Ключ хранится только в зашифрованном виде у создателя. Пул и поддержка не хранят данные о созданных ключах.

Список ключей

После создания ключ появляется в таблице раздела «API-ключи». В ней отображается:

• Название и маскированное значение — первые символы (префикс) и последующие шесть знаков для идентификации
• Сущность — к каким объектам привязан ключ
• Уровень доступа
• Кнопка отзыва (корзина)

⚠️ Полное значение ключа нигде не хранится и не отображается — ни в интерфейсе, ни у команды Headframe.

Как отозвать ключ

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

1. Найдите нужный ключ в списке и нажмите на иконку корзины справа.

2. Подтвердите действие через двухфакторную аутентификацию.

3. Ключ немедленно деактивируется. Все сервисы, использующие его, потеряют доступ к API.

Отозванные ключи перемещаются в раздел «Отозванные ключи» — он появляется ниже основного списка. Там сохраняется информация о названии, скоупе и уровне доступа отозванного ключа, но удалить его повторно или восстановить нельзя.

⚠️  Действие необратимо. Если нужен новый ключ с теми же правами — просто создайте его заново.

Что делать, если ключ потерян

Если вы не сохранили ключ после создания — восстановить его невозможно. Это сделано намеренно: полное значение ключа нигде не хранится.

Правильный флоу:

1. Отзовите старый ключ (или просто оставьте его — он продолжит работать, пока его не удалите).
2. Создайте новый ключ с нужными настройками.
3. Обновите ключ во всех местах, где он используется.

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

Документация

https://developers.headframe.io/

Частые вопросы

Сколько ключей можно создать?
Ограничений нет. Создавайте столько ключей, сколько нужно — с разными уровнями доступа и скоупами для разных задач.

Работают ли ключи, которые выдавались через поддержку?
Да, старые ключи продолжают работать. Но они не отображаются в интерфейсе и не обновляются автоматически при добавлении новых сущностей. Если хотите полноценно управлять ключами — создайте новые через раздел «Доступы».

Нужна ли двухфакторная аутентификация для работы с ключами?
Да — и для создания, и для отзыва ключа потребуется подтверждение через 2FA.

Можно ли изменить права существующего ключа?
Нет. Уровень доступа и скоуп задаются при создании и не меняются. Если нужны другие права — отзовите старый ключ и создайте новый.

Видит ли поддержка мои ключи?
Нет. Ключи хранятся в хешированном виде. Ни команда Headframe, ни поддержка не могут увидеть полное значение вашего ключа.