Authentication

Use either header. When both are present, X-API-Key wins. Surrounding whitespace is ignored; keys longer than 256 bytes are rejected.

curl -H "X-API-Key: $LOCATE_ME_KEY" \
  http://localhost:8080/v1/lookup/8.8.8.8

curl -H "Authorization: Bearer $LOCATE_ME_KEY" \
  http://localhost:8080/v1/lookup/8.8.8.8

Keys are never accepted in the URL, where they would end up in proxy logs and browser history. The API sends no CORS headers, so browsers cannot call it cross-origin: keep keys on your servers.

A key is lm_ followed by 64 hex characters: 256 bits from the operating system's random number generator. gen-key prints the key once, with the entry to paste into config.toml.

locate-me gen-key --name my-client

[[api_keys]]
name = "my-client"     # label in logs and metrics: [A-Za-z0-9_.-]{1,64}
sha256 = "5f0c…"       # SHA-256 of the key, 64 hex characters
# rate_per_sec = 100   # overrides limits.default_rate_per_sec
# burst = 200          # overrides limits.default_burst
# enabled = true       # false revokes the key without deleting it

To register a key that already exists, pipe it into hash-key and paste the digest as sha256.

printf %s "$EXISTING_KEY" | locate-me hash-key

The configuration file is polled every 5 seconds and re-read on SIGHUP. Key changes apply without a restart:

• Add the new key's entry, deploy it to clients, then delete the old entry.
• Set enabled = false to revoke a key at once. It stops working within 5 seconds.
• A file that fails validation is rejected and the running configuration stays in place.

A missing, unknown or disabled key gets 401 unauthorized with a WWW-Authenticate: Bearer realm="locate-me" header.

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="locate-me"

{
  "error": "unauthorized",
  "message": "a valid API key is required (X-API-Key or Authorization: Bearer)"
}

Failed attempts are throttled per client address, with IPv6 grouped per /64. Past limits.auth_failure_burst (10) failures, a client gets 429 rate_limited and may fail again at limits.auth_failures_per_minute (30). The table of tracked clients is bounded by limits.max_tracked_clients.

Behind a reverse proxy every request seems to come from the proxy. List it in server.trusted_proxies so throttling targets the real client from X-Forwarded-For. The header is ignored from any other source.