> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poplock.scyne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How the PopLock API authenticates requests and what to expect when auth fails.

## 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.

```bash theme={null}
# 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`:

```bash theme={null}
# 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`:

```json theme={null}
{
  "ok": false,
  "error": "Unauthorized — X-API-Key required for write endpoints."
}
```

<Note>
  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.`
</Note>

## Security considerations

* Store the API key in `/etc/poplock-api.conf` with `chmod 600` permissions. See [Installation](/api/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.