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

API Key, Access Token и авторизация

Включение API RustMinerSystem, API Key, Access Token, заголовок X-ACCESS-TOKEN, ротация и безопасное использование.

API Key, Access Token и авторизация

RustMinerSystem создает краткосрочный Access Token на основе API Key. Затем сторонний client авторизует запросы к открытому API заголовком X-ACCESS-TOKEN.

1. Включение API

Установите в rust-config:

ENABLE_CONTROL_API=1

Перезапустите RustMinerSystem, откройте «Настройки → API» и нажмите «Проверить снова». При установке скриптом можно повторно запустить installer и выбрать «Включить API».

Если функция выключена, frontend распознает status: -3 или сообщение Api Control Disable как отключенное состояние API.

2. Получение или обновление API Key

Страница настроек API использует:

Метод	Путь	Назначение
GET	`/api/access/key`	Получить текущий API Key и проверить, включено ли управление API.
POST	`/api/refresh/access/key`	Впервые создать либо обновить API Key. Успешный ответ — `Ok`.

Успешное чтение возвращает:

{
  "key": "<API_KEY>"
}

Эти два endpoint управляются на странице настроек API. Передавайте API Key потребителям через защищенный канал.

Обновление API Key является глобальной ротацией: старый Key и все созданные им Access Token немедленно становятся недействительными. Текущий frontend не позволяет создавать отдельные Key для разных потребителей.

3. Создание Access Token

POST /{safe-route}/api/generate/access/token
Content-Type: application/json

{
  "k": "<API_KEY>"
}

Успешный ответ:

{
  "access_token": "<ACCESS_TOKEN>"
}

Access Token действует примерно два часа. После истечения создайте новый Token с текущим API Key. Создание любого нового Access Token делает предыдущий Token недействительным, поэтому все потребители одного экземпляра должны согласовывать обновление.

Используйте API Key только для создания Access Token. Не отправляйте Key как credential обычных endpoints. Frontend показывает созданный Token только в состоянии текущей страницы, поэтому сразу скопируйте его в безопасное хранилище secrets.

4. Вызов открытого endpoint

Передавайте официальный заголовок из конфигурации frontend в каждом запросе:

GET /{safe-route}/api/ports
X-ACCESS-TOKEN: <ACCESS_TOKEN>
Content-Type: application/json

Передавайте созданный Access Token непосредственно как значение X-ACCESS-TOKEN без дополнительного префикса.

Пример curl:

curl --request GET \
  --url 'https://miner.example.com/rms-admin/api/ports' \
  --header 'X-ACCESS-TOKEN: <ACCESS_TOKEN>' \
  --header 'Accept: application/json'

Жизненный цикл credentials

Событие	Результат
Создание нового Access Token	Новый Token начинает действовать, предыдущий немедленно отключается.
Истечение Access Token	Создайте новый Token с текущим API Key; срок — примерно два часа.
Обновление API Key	Старый Key и все старые Access Token немедленно отключаются.
`ENABLE_CONTROL_API=0` и перезапуск	Управление API выключается, существующие credentials перестают использоваться.

Текущий frontend не показывает read-only/admin scopes, правила source IP, настройки CORS или rate limit API. Считайте Access Token высокопривилегированным secret и настраивайте ограничения источника и частоты запросов на reverse proxy либо firewall.

Специальный read-only credential

Observer продолжает использовать отдельный заголовок:

X-OB-TOKEN: <Observer token>

Он действует только для read-only endpoints Observer и не является общим credential X-ACCESS-TOKEN.

Диагностика

Симптом	Действие
Страница API показывает «Не включено»	Проверьте `ENABLE_CONTROL_API=1`, перезапустите программу и повторите проверку.
Ответ создания Token не содержит `access_token`	Убедитесь, что Key не обновлялся, поле запроса записано как `k`, и проверьте `message` в ответе.
Обычный endpoint возвращает `401` / `403`	Проверьте имя и значение header, затем создайте новый Token с текущим Key.
Несколько потребителей отказали одновременно	Проверьте, не обновлялся ли Key и не создал ли другой потребитель новый Access Token.

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

Передавайте API credentials только через HTTPS.
Не помещайте credential в URL, query string, логи и screenshots.
У экземпляра есть один видимый во frontend поток Key/Token; согласовывайте ротацию между всеми потребителями.
Загружайте secrets из environment variables или secret manager.
При утечке Access Token немедленно создайте новый Token; при утечке API Key обновите Key.
Для изменения ports, wallets, сертификатов и firewall добавьте более строгие правила источника на reverse proxy.