> For the complete documentation index, see [llms.txt](https://docs.k9.io/key9-identity/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.k9.io/key9-identity/maxmind-api-proxy/configuration/tls.md).

# TLS / HTTPS Setup

Enabling TLS is strongly recommended whenever `maxmind-api-proxy` is reachable by clients over a network, since the `API_KEY` header and MaxMind responses would otherwise travel in plaintext.

***

## Enabling TLS

Set the following fields in your config file:

```json
{
  "http_tls":  true,
  "http_cert": "/path/to/fullchain.pem",
  "http_key":  "/path/to/privkey.pem",
  "http_listen": ":8443"
}
```

| Field       | Description                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `http_tls`  | Must be `true` to activate TLS.                                                                 |
| `http_cert` | Absolute path to the certificate file in PEM format. For Let's Encrypt this is `fullchain.pem`. |
| `http_key`  | Absolute path to the private key file in PEM format. For Let's Encrypt this is `privkey.pem`.   |

The proxy uses Go's standard `net/http` TLS stack, which supports TLS 1.2 and 1.3.

***

## Using Let's Encrypt (Certbot)

[Certbot](https://certbot.eff.org/) is the most common way to obtain free, auto-renewing TLS certificates.

### Install and obtain a certificate

```bash
# Debian / Ubuntu
sudo apt install certbot

# Obtain a certificate (standalone mode — stop any web server first)
sudo certbot certonly --standalone -d yourproxy.example.com
```

Certbot stores certificates under `/etc/letsencrypt/live/<domain>/`. Update your config:

```json
{
  "http_cert": "/etc/letsencrypt/live/yourproxy.example.com/fullchain.pem",
  "http_key":  "/etc/letsencrypt/live/yourproxy.example.com/privkey.pem"
}
```

### Certificate renewal

Certbot installs a systemd timer or cron job that renews certificates automatically. After renewal the proxy must be restarted for it to load the new certificate:

```bash
# Add a renewal hook to restart the proxy after each renewal
echo "systemctl restart maxmind-api-proxy" > /etc/letsencrypt/renewal-hooks/deploy/restart-proxy.sh
chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-proxy.sh
```

***

## Using a self-signed certificate (internal / testing)

For internal networks where you control the CA trust, you can generate a self-signed certificate:

```bash
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout proxy.key \
  -out proxy.crt \
  -subj "/CN=maxmind-proxy" \
  -addext "subjectAltName=IP:192.168.1.10,DNS:proxy.internal"
```

Then set `http_cert` to `proxy.crt` and `http_key` to `proxy.key`. Clients querying with `curl` will need `-k` (or `--insecure`) unless the certificate is added to their trust store.

***

## Running without TLS

For localhost-only deployments or environments where TLS is terminated upstream (e.g. nginx, HAProxy, a cloud load balancer), you can run the proxy without TLS:

```json
{
  "http_tls":    false,
  "http_listen": "127.0.0.1:8080",
  "http_cert":   "unused",
  "http_key":    "unused"
}
```

> The config parser requires `http_cert` and `http_key` to be non-empty strings even when `http_tls` is `false`. Supply any non-empty placeholder value.