RustMinerSystem

Documentation

API Key, Access Token, and Authentication

RustMinerSystem API enablement, API Key and Access Token workflow, X-ACCESS-TOKEN header, rotation, and secure use.

API Key, Access Token, and Authentication

RustMinerSystem generates a short-lived Access Token from an API Key. Third-party clients then authenticate open API requests with the X-ACCESS-TOKEN header.

1. Enable the API

Set the following value in rust-config:

ENABLE_CONTROL_API=1

Restart RustMinerSystem, open “Settings → API,” and select “Detect again.” Script-install users can instead rerun the installer and select “Enable API.”

When the feature is off, the frontend recognizes status: -3 or the message Api Control Disable as the disabled state.

2. Read or refresh the API Key

The API settings screen uses:

Method Path Purpose
GET /api/access/key Read the current API Key and detect whether API control is enabled.
POST /api/refresh/access/key Create the first API Key or rotate the current Key. A successful response is Ok.

A successful read returns:

{
  "key": "<API_KEY>"
}

These two endpoints are managed from the API settings screen. Provision the API Key to consumers through a secure channel.

Refreshing the API Key is a global rotation: the old Key and every Access Token generated from it become invalid immediately. The current frontend does not provide multiple Keys for separate consumers.

3. Generate an Access Token

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

{
  "k": "<API_KEY>"
}

Successful response:

{
  "access_token": "<ACCESS_TOKEN>"
}

The Access Token is valid for approximately two hours. Generate a new token from the current API Key after expiry. Generating any new Access Token invalidates the previous token, so all consumers of one instance must coordinate updates.

Use the API Key only to generate an Access Token. Do not send the Key as the credential for regular endpoints. The frontend displays a generated token only in the current page state, so copy it immediately into a secure secret store.

4. Call an open endpoint

Send the official header defined by the frontend with every request:

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

Use the generated Access Token directly as the X-ACCESS-TOKEN value without an additional prefix.

curl example:

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

Credential lifecycle

Event Effect
Generate another Access Token The new token becomes active and the previous token immediately stops working.
Access Token expires Generate a new token from the current API Key, approximately every two hours.
Refresh the API Key The old Key and all old Access Tokens immediately stop working.
Set ENABLE_CONTROL_API=0 and restart API control is disabled and existing credentials stop being usable.

The current frontend exposes no read-only/admin scopes, source-IP rules, CORS settings, or API rate-limit configuration. Treat the Access Token as a high-privilege secret and apply source restrictions and throttling at the reverse proxy or firewall.

Special read-only credential

Observer mode continues to use its separate header:

X-OB-TOKEN: <Observer token>

It applies only to Observer read-only endpoints and is not the general X-ACCESS-TOKEN credential.

Troubleshooting

Symptom Action
The API settings page shows “Disabled” Verify ENABLE_CONTROL_API=1, restart the program, and detect again.
Token generation returns no access_token Confirm the Key was not rotated, the request field is lowercase k, and inspect the response message.
A regular endpoint returns 401 / 403 Check the header name and value, then generate a fresh token from the current Key.
Several consumers fail at the same time Check whether the Key was refreshed or another consumer generated a new Access Token.

Security guidance

  • Transmit API credentials only over HTTPS.
  • Never place a credential in a URL, query string, log, or screenshot.
  • The current instance has one frontend-visible Key/Token flow; coordinate rotation among all consumers.
  • Load secrets from environment variables or a secret manager.
  • Regenerate the Access Token immediately after token exposure; refresh the API Key after Key exposure.
  • Add stricter reverse-proxy source rules for port, wallet, certificate, and firewall mutations.