> 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/configuration.md).

# Configuration File Reference

`maxmind-api-proxy` is configured through a single JSON file whose path is passed as the first argument on the command line:

```bash
./maxmind-api-proxy /etc/maxmind-api-proxy/config.json
```

The proxy will exit with a fatal error if the file cannot be opened, if the JSON is malformed, or if any required field is missing or empty.

***

## Full example

```json
{
  "api_key": "YOUR_PROXY_SERVICE_API_KEY",
  "cache_errors": false,

  "http_listen": ":8443",
  "http_tls": true,
  "http_cert": "/etc/letsencrypt/live/yoursite.example.com/fullchain.pem",
  "http_key":  "/etc/letsencrypt/live/yoursite.example.com/privkey.pem",
  "http_mode": "release",

  "maxmind_username": "123456",
  "maxmind_password": "your_maxmind_license_key",
  "maxmind_url": "https://geoip.maxmind.com/geoip/v2.1/city/",

  "redis_host":       "127.0.0.1",
  "redis_port":       6379,
  "redis_password":   "your_redis_password",
  "redis_database":   "0",
  "redis_cache_time": 24
}
```

***

## Field reference

### Proxy authentication

| Field     | Type   | Required | Description                                                                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `api_key` | string | Yes      | The secret key clients must supply in the `API_KEY` HTTP header to use the proxy. Choose a long, random string. |

***

### HTTP server

| Field         | Type   | Required | Description                                                                                                                                                 |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `http_listen` | string | Yes      | Address and port to listen on. Use `:8443` to listen on all interfaces on port 8443, or `127.0.0.1:8080` to restrict to localhost.                          |
| `http_tls`    | bool   | Yes      | Set to `true` to enable TLS. See [TLS Setup](/key9-identity/maxmind-api-proxy/configuration/tls.md).                                                        |
| `http_cert`   | string | Yes      | Path to the TLS certificate file (PEM). Required by the config parser even when `http_tls` is `false`; supply a placeholder path if not using TLS.          |
| `http_key`    | string | Yes      | Path to the TLS private key file (PEM). Same note as `http_cert`.                                                                                           |
| `http_mode`   | string | Yes      | Logging/runtime mode. See [Run Modes](/key9-identity/maxmind-api-proxy/configuration/run-modes.md). Valid values: `debug`, `release`, `test`, `production`. |

***

### MaxMind upstream

| Field              | Type   | Required | Description                                                                                                                             |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `maxmind_username` | string | Yes      | Your MaxMind account ID (numeric string). Found in your MaxMind account portal under **My Account → Account Information**.              |
| `maxmind_password` | string | Yes      | Your MaxMind license key.                                                                                                               |
| `maxmind_url`      | string | Yes      | The MaxMind GeoIP2 API endpoint to query. The IP address is appended to this URL. Default: `https://geoip.maxmind.com/geoip/v2.1/city/` |

#### Available MaxMind endpoints

MaxMind offers several precision web service databases. Swap `maxmind_url` depending on the data you need:

| Database           | URL                                              |
| ------------------ | ------------------------------------------------ |
| City (recommended) | `https://geoip.maxmind.com/geoip/v2.1/city/`     |
| Country            | `https://geoip.maxmind.com/geoip/v2.1/country/`  |
| Insights           | `https://geoip.maxmind.com/geoip/v2.1/insights/` |

***

### Redis cache

| Field              | Type    | Required | Description                                                                                                                                                                                                                  |
| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redis_host`       | string  | Yes      | Hostname or IP address of the Redis server.                                                                                                                                                                                  |
| `redis_port`       | integer | Yes      | Port Redis is listening on (typically `6379`).                                                                                                                                                                               |
| `redis_password`   | string  | Yes      | Password for Redis authentication.                                                                                                                                                                                           |
| `redis_database`   | string  | Yes      | Redis logical database index (e.g. `"0"`).                                                                                                                                                                                   |
| `redis_cache_time` | integer | Yes      | How long to cache each result, **in hours**. After this TTL expires Redis automatically removes the entry and the next query will hit MaxMind again.                                                                         |
| `cache_errors`     | bool    | Yes      | When `true`, error responses from MaxMind (responses containing an `"error"` field) are also stored in Redis and served from cache. When `false` (recommended), errors are not cached so transient failures don't get stuck. |

***

## Notes

* The config file is read once at startup. To apply changes, restart the process.
* Protect the config file with filesystem permissions (`chmod 600`) since it contains your MaxMind credentials and Redis password.