Authentication

API keys

Create keys in the dashboard. Send one as a bearer token, or in X-Api-Key:

curl "https://geo-coder-service.vercel.app/v1/account" \  -H "Authorization: Bearer $GEOCODE_API_KEY"

• Keys start with geo_ and are shown once. We store only a hash.
• Use one key per app or environment, so you can revoke one without touching the others.
• Keep keys on the server. Never ship one in a browser bundle or a mobile app.

Without a key

Public ops work anonymously, rate-limited to 20 calls a minute per IP: search_boundaries, list_children, get_pricing, and get_boundary at detail=low. The API reference marks each op.

OAuth (MCP connectors)

Chat apps that add MCP servers as connectors (Claude.ai, ChatGPT) sign in with OAuth 2.1. Give them https://geo-coder-service.vercel.app/mcp?auth=required: the server answers 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource, the app sends you to sign in and approve, and it gets a token for your account.

CLI device sign-in

npx @meterapp/geocode login shows a code and opens /activate in your browser. Approve it and the CLI receives a new API key, saved in ~/.config/geocode. It works over SSH too: open the link on any device. On CI, set GEOCODE_API_KEY instead.

Errors

A missing key on a paid op answers 401 unauthorized; a revoked or unknown key 401 invalid_key.