Skip to main content

​
Endpoint tiers

The API uses a two-tier model based on HTTP method:
TierMethodsAuth required
PublicGETNo — call directly
WritePOSTYes — X-API-Key header required
Public endpoints expose read-only server state. Write endpoints control the server and require your configured secret key.

​
Passing the API key

Include the key in the X-API-Key request header. 
# Start the server
curl -X POST http://your-server:6767/api/server/start \
  -H "X-API-Key: your_secret_key_here"
For endpoints that accept a JSON body, also set Content-Type: 
# Send a console command
curl -X POST http://your-server:6767/api/command \
  -H "X-API-Key: your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Server restarting in 5 minutes"}'

​
Error responses

A missing or incorrect key on a write endpoint returns HTTP 401: 
{
  "ok": false,
  "error": "Unauthorized — X-API-Key required for write endpoints."
}
If no API_KEY is set in /etc/poplock-api.conf, write endpoints are disabled entirely. The server logs a warning at startup: [WARN] No API_KEY set — write endpoints are disabled until one is configured.

​
Security considerations

  • Store the API key in /etc/poplock-api.conf with chmod 600 permissions. See Installation for setup steps.
  • Never share the API key in Discord messages or public channels. The intended deployment pattern is to store the key inside n8n, which acts as a relay — Discord users hit n8n webhooks, n8n validates their roles, and n8n proxies authorized requests to the PopLock API.
  • The API sets Access-Control-Allow-Origin: * on all responses. To limit access to trusted hosts, restrict inbound traffic to port 6767 at the firewall level rather than relying on CORS alone.