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.

Every request sent to the HungerBridge HTTP API must carry a shared secret token in the X-Auth-Key header. The server checks this header against the value stored in config.yaml before processing any endpoint — if the header is absent or the value does not match, the request is rejected immediately with an HTTP 401 response. This applies universally across all endpoints, from legacy /run to the modern /v2/* routes.

​
How Authentication Works

HungerBridge implements authentication inside BridgeServer.auth(), which is the first check executed by every HTTP handler. The method reads the X-Auth-Key header from the incoming request and compares it to the key loaded from configuration at startup: 
private boolean auth(HttpExchange ex) {
    String key = ex.getRequestHeaders().getFirst("X-Auth-Key");
    return key != null && key.equals(config.getAuthKey());
}
Both conditions must be true — the header must be present and its value must match exactly. There is no fallback, no grace period, and no alternative authentication mechanism. Authentication is always enforced; there is no toggle to disable it.

​
Finding Your Auth Key

On the very first startup, HungerBridge generates a random UUID and writes it to config.yaml under the auth.key field. The key location depends on which server platform you are running.

Fabric

config/HungerBridge/config.yaml relative to your server root

Paper / Purpur

plugins/HungerBridge/config.yaml relative to your server root
Open the file and locate the auth block:
config.yaml
port: 30007

auth:
  key: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
The key value is what you must supply as the X-Auth-Key header in every request.

​
Changing the Auth Key

1

Stop your Minecraft server

Shut down the server cleanly so HungerBridge releases its file handles before you edit the config.
2

Edit config.yaml

Open config/HungerBridge/config.yaml (Fabric) or plugins/HungerBridge/config.yaml (Paper) and replace the value of auth.key with your new secret:
config.yaml
auth:
  key: "your-new-secret-key-here"
You can use any string value — a new UUID, a long passphrase, or any token your tooling generates.
3

Restart the server

HungerBridge reads the configuration once at startup. The new key takes effect immediately after the server comes back online.
4

Update HungerLib

Update the corresponding secret in your HungerLib configuration so requests from HungerLib continue to authenticate successfully.

​
Making Authenticated Requests

Pass the key in the X-Auth-Key header on every call. The examples below use the default port 30007. 
curl -s \
  -H "X-Auth-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  http://localhost:30007/v2/ping
A successful ping response looks like: 
{
  "ok": true,
  "server_time": 1718000000000
}

​
Authentication Failure

When the X-Auth-Key header is missing or its value does not match the configured key, HungerBridge returns an HTTP 401 with the following JSON body: 
{
  "ok": false,
  "error": "unauthorized",
  "message": "Invalid X-Auth-Key"
}
The same 401 response is returned whether the header is absent or simply incorrect. HungerBridge does not distinguish between the two cases.

​
Security Recommendations

The auth key is a shared secret — anyone who holds it can execute arbitrary console commands on your server. Treat it accordingly.

Keep the Key Private

Never commit config.yaml to version control or paste the key into public chat. Rotate the key if you suspect it has been exposed.

Restrict Network Access

HungerBridge binds to all interfaces by default. Use a firewall (e.g. ufw, iptables, or your host’s security group) to block the HungerBridge port from public internet access.

Bind to Localhost

If HungerLib and HungerBridge run on the same machine, block the port externally so traffic never leaves the host — the auth key then only needs to protect against local processes.

Use a Strong Key

The auto-generated UUID is sufficient entropy for most setups, but you can substitute any high-entropy string. Avoid short or guessable values.
HungerBridge does not support TLS. If HungerLib communicates with HungerBridge over a network, the auth key travels in plaintext. Restrict the port to a trusted private network or a loopback interface to mitigate interception risk.

Build docs developers (and LLMs) love

Get started for freeTalk to us