Authentication

Every request that uses your balance needs an API key. One key works across the whole API: Claude, GPT and Gemini models, data tools, the browser agent and the MCP server.

Get an API key#

Create a key under API keys in the dashboard. A key looks like lr- followed by 40 letters and digits. It is shown once, when you create it. Lovely Router stores only a hash of the key, so a lost key can't be recovered: revoke it and create a new one.

Keep the key in an environment variable. Every example in these docs reads it from $LOVELY_API_KEY.

export LOVELY_API_KEY="lr-..."

To limit what a key can spend or call, see API keys.

Send the key#

Lovely Router accepts the key in any of the places the vendor APIs use. All four work on every endpoint, so keep whatever your SDK or tool sends by default.

If a request carries more than one, the first match wins in this order: Authorization: Bearer, x-api-key, x-goog-api-key, ?key=.

Check that a key works#

Counting tokens needs a valid key but costs nothing, which makes it a quick check. A 200 means the key is active and allowed to use the model.

curl https://lovelyrouter.com/v1/messages/count_tokens \
  -H "x-api-key: $LOVELY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Endpoints that don't need a key#

Catalog endpoints are public, so you can browse models and tools before you sign up. A key sent to them is ignored, except by the planner, which uses it for a higher limit.

Everything else needs a key: model requests (including token counting), tool runs, every /v1/browser endpoint, and running tools over MCP.

Authentication errors#

A missing, unknown, revoked or expired key returns 401. The body uses the format of the API you called.

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or revoked API key"}}

A valid key can still be refused for what it's allowed to do: 403 for a model outside its allow-list, 402 when its spend limit is reached, 429 when it hits its rate limit. See What happens when a limit is hit and Errors.

Keep keys safe#

• Keep keys on the server. Never put a key in a web page, mobile app or anything else you ship to users. The API accepts requests from any origin, so a key in front-end code can be copied and spent by anyone who opens it.
• Load keys from the environment or a secrets manager. Don't commit them. Add .env files to .gitignore.
• Use one key per app and environment. A leaked staging key then can't touch production, and Logs show which key made each request.
• Cap what each key can do. Set a spend limit, a model allow-list and an expiry date on keys used by agents, CI jobs or other people. See API keys.
• Rotate keys regularly, and right away when someone with access leaves. See Rotate a key.