Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerBridge/llms.txt

Use this file to discover all available pages before exploring further.

Most HungerBridge endpoints — across all three API generations — are protected by a shared-secret key. The server checks each incoming request for a matching X-Auth-Key header before processing it. No key, or a wrong key, results in an immediate 401 Unauthorized response. Two endpoints, GET /v1/status and GET /v1/version, do not call the auth check and will respond to any caller that can reach the port (when those endpoints are enabled).

​
The X-Auth-Key Header

​
X-Auth-Key
string
required
The shared secret that authorizes the request. Must exactly match the auth.key value in config.yaml. The comparison is case-sensitive and byte-exact — no trimming or normalization is applied.

​
Obtaining the Key

The authentication key lives in config.yaml under the auth section: 
auth:
  key: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
If config.yaml does not exist when HungerBridge starts, the plugin auto-generates a fresh file with a randomly generated UUID as the key. The generated file is written to the plugin’s configuration directory (e.g. plugins/HungerBridge/config.yaml on Paper/Purpur, or the equivalent Fabric config path).
Copy the generated key from config.yaml into your HungerLib configuration so both sides share the same secret. You can replace the UUID with any string you prefer — just restart the server after editing the file.

​
Making an Authenticated Request

Pass the key in the X-Auth-Key header on every request. The example below calls the v2 ping endpoint: 
curl -X GET http://127.0.0.1:30007/v2/ping \
  -H "X-Auth-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
A successful response: 
{
  "ok": true,
  "server_time": 1718000000000
}

​
401 Unauthorized — Invalid or Missing Key

When the X-Auth-Key header is absent or does not match the configured key, HungerBridge returns: 
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "ok": false,
  "error": "unauthorized",
  "message": "Invalid X-Auth-Key"
}
The same error body is returned whether the header is entirely missing or simply contains the wrong value.

​
Endpoints That Skip Auth

Two v1 endpoints do not invoke the auth check at all and therefore respond without requiring a key:
EndpointNotes
GET /v1/statusReturns bridge version, platform, and Minecraft version as flat fields alongside ok.
GET /v1/versionReturns version metadata; response does not include an ok field.
Both endpoints must still be enabled in config.yaml (they are disabled by default). A disabled endpoint returns 403 Forbidden before any auth check would occur.

​
Security Best Practices

HungerBridge does not implement HTTPS. Your X-Auth-Key is transmitted in plain text over the network. Never expose the API port to untrusted networks.
Keep the following recommendations in mind when deploying HungerBridge:
  • Bind to localhost when possible. If HungerLib runs on the same host as the Minecraft server, set the server to listen on 127.0.0.1 (or leave the OS default) so the port is not reachable from other machines.
  • Restrict the port with a firewall. Use iptables, ufw, or your cloud provider’s security group rules to allow connections only from trusted IP addresses.
  • Use a VPN or SSH tunnel for remote access. If HungerLib must connect over a network, route the connection through WireGuard, OpenVPN, or an SSH port forward to ensure the key is never transmitted in clear text across untrusted networks.
  • Treat the key like a password. Use a sufficiently long, random value. The default auto-generated UUID (128 bits of entropy) is a good baseline.
  • Rotate the key if it is ever compromised. Update auth.key in config.yaml and restart the server, then update HungerLib’s configuration to match.

Build docs developers (and LLMs) love

Get started for freeTalk to us