Authentication

Every request to /v1/* needs an API key. The same key authenticates lookups, the account endpoints and the MCP server. The one other credential is an OAuth access token, which opens the MCP server only (see MCP server); it never works on the REST API.

YOUR_API_HOST in the examples on this page stands for the API address that comes with your key.

Send your key

Use the Authorization header with the Bearer scheme:

curl https://YOUR_API_HOST/v1/account \
  -H "Authorization: Bearer $LOOKVALID_API_KEY"

If your client cannot set an Authorization header, send the key in an X-API-Key header instead:

curl https://YOUR_API_HOST/v1/account \
  -H "X-API-Key: $LOOKVALID_API_KEY"

If both are present, the Authorization header wins. Never put a key in a URL or a query string.

About keys

• Keys look like lv_live_ followed by 43 letters and digits.
• A key is shown once, when you create it. We store only a one-way hash, so a lost key cannot be recovered. Create a new one instead.
• GET /v1/account lists your keys by id and prefix. It never returns a full key.
• You can have several keys. Use one per application or environment so you can revoke one without touching the others.
• All keys on an account share one credit balance.

Keep keys safe

• Call the API from your server. Anything shipped to a browser or mobile app can be extracted.
• Read keys from environment variables or a secret manager, not from source files.
• Rotate a key by creating a new one, deploying it, then revoking the old one in the dashboard.
• If a key leaks, revoke it. A revoked key stops working on the next request.

When authentication fails

A missing, malformed, revoked or unknown key returns HTTP 401 with the unauthorized error and a WWW-Authenticate: Bearer header. The response is the same for every one of those cases, so it does not reveal which keys exist. Nothing is charged.

1{
2  "error": {
3    "code": "unauthorized",
4    "message": "The API key is missing, malformed, revoked or unknown.",
5    "fix": "Send a valid key in the Authorization header as \"Bearer <key>\". If the key was revoked, create a new one and retry.",
6    "docs_url": "/docs/errors#unauthorized",
7    "retryable": false,
8    "request_id": "req_..."
9  }
10}