Authentication

Endpoint tiers

The API uses a two-tier model based on HTTP method:

Tier	Methods	Auth required
Public	`GET`	No — call directly
Write	`POST`	Yes — `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.

Overview

Endpoints

Integrations

Endpoint tiers

Passing the API key

Error responses

Security considerations

​Endpoint tiers

​Passing the API key

​Error responses

​Security considerations

Endpoint tiers

Passing the API key

Error responses

Security considerations