---
title: "Authentication"
url: "https://lookvalid.com/docs/authentication.md"
canonical_url: "https://lookvalid.com/docs/authentication"
last_updated: "2026-10-22"
type: "reference"
summary: "How to send your LookValid API key, how keys are stored and how to keep them safe."
related: ["https://lookvalid.com/docs/quickstart.md"]
---

# Authentication

How to send your LookValid API key, how keys are stored and how to keep them safe.

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](https://lookvalid.com/docs/mcp.md#sign-in-with-oauth)); 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:

```sh
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:

```sh
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`](https://lookvalid.com/docs/errors.md#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.

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

## Related

- [Quickstart](https://lookvalid.com/docs/quickstart.md)