> 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/api-reference/authentication.md).

# Authentication

Every request to `maxmind-api-proxy` must include a valid API key. The proxy uses a single shared secret configured in the `api_key` field of the config file.

***

## How to authenticate

Include the API key in the `API_KEY` HTTP request header:

```
API_KEY: your-secret-key
```

### curl

```bash
curl -H 'API_KEY: your-secret-key' https://yourproxy.example.com:8443/8.8.8.8
```

### Python (requests)

```python
import requests

response = requests.get(
    "https://yourproxy.example.com:8443/8.8.8.8",
    headers={"API_KEY": "your-secret-key"}
)
print(response.json())
```

### Go

```go
req, _ := http.NewRequest("GET", "https://yourproxy.example.com:8443/8.8.8.8", nil)
req.Header.Set("API_KEY", "your-secret-key")
resp, _ := http.DefaultClient.Do(req)
```

***

## Authentication failure

If the `API_KEY` header is missing or the value does not match, the proxy returns:

```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error": "api authentication failed"}
```

The request is rejected immediately and does not reach MaxMind or Redis.

***

## Choosing a strong API key

The `api_key` is a shared secret. Use a randomly generated value of at least 32 characters:

```bash
# Generate a suitable key
openssl rand -hex 32
```

Store the key only in the config file (protected with `chmod 600`) and in your clients' secret management system (e.g. Vault, AWS Secrets Manager, Kubernetes Secrets). Do not hard-code it in application source code.