RustMinerSystem

Documentation

API Headers and Authentication

Login-free RustMinerSystem API calls, custom authentication headers, permission boundaries, and internal UI session endpoints.

API Headers and Authentication

External RustMinerSystem API calls do not require a management-UI login and do not require a backend login token. Third-party clients authenticate each request through the dedicated custom request header.

Core rules

  • Do not call /api/_/key.
  • Do not call /api/_/login.
  • Do not store the management username or password.
  • Do not use the UI’s Authorization: Bearer <login token> as a public API credential.
  • Send the configured custom authentication header directly with every API request.

Request example

After the custom-header feature is implemented, a request will have this form:

GET /{safe-route}/api/ports
<custom header name>: <API credential>
Content-Type: application/json

The final header name, credential format, and creation workflow are not implemented in the current backend. This documentation therefore uses placeholders instead of inventing a field name.

Authentication contract still to be defined

When the feature is complete, this chapter must document:

  • The official request-header name.
  • How credentials are generated, viewed, and copied.
  • Read-only and administrative scopes.
  • Which endpoints each scope can access.
  • Expiration and rotation.
  • Revocation and regeneration.
  • Source-IP, CORS, and rate-limit rules.
  • Error codes for missing, invalid, expired, or insufficient credentials.

Until those rules are finalized, a backend login token must not be embedded in third-party applications as a substitute.

Internal management-UI session endpoints

The bundled management UI still uses the following session endpoints. They are not prerequisites for third-party API calls:

Method Path Internal UI purpose
GET /api/_/key Obtain the management-login encryption key.
POST /api/_/login Log in to the management UI.
POST /api/_/verify Verify management-login TOTP.
POST /api/_/logout End the UI session.
POST /api/_/changepassword Change management credentials.
POST /api/_/setting/code Enable UI TOTP.
DELETE /api/_/setting/code Disable UI TOTP.
GET /api/2step/route Read the UI TOTP-protected endpoint list.
POST /api/2step/route Save the UI TOTP-protected endpoint list.
POST /api/token/exp Set the UI session lifetime.

External API clients do not call these endpoints and do not implement the AES login-encryption flow.

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 future general API credential.

Security guidance

  • Transmit API credentials only over HTTPS.
  • Never place a credential in a URL, query string, log, or screenshot.
  • Issue separate credentials to different callers.
  • Load secrets from environment variables or a secret manager.
  • Revoke and regenerate a leaked credential immediately.
  • Apply stricter scopes to port, wallet, certificate, and firewall mutations.