> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdrift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Lightdrift API and MCP authentication

> Choose the right credential for REST, Images MCP, or Docs MCP; fix connection symptoms and verify one image-search request safely.

If you are wiring image search into a presentation builder, website agent, or content pipeline, first identify which Lightdrift endpoint your application actually uses. A browser sign-in, an API key, and access to public documentation serve different purposes.

## Match the endpoint to the credential

| Connection                              | Endpoint                              | Documented authentication                                                                                                    |
| --------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [REST API](/api-reference/introduction) | `https://api.lightdrift.ai/v1/search` | API key in the `X-API-Key` request header.                                                                                   |
| [Images MCP](/guides/images-mcp)        | `https://lightdrift.ai/mcp`           | Lightdrift browser sign-in (OAuth), or `X-API-Key` if your client supports custom headers. Choose one method per connection. |
| [Docs MCP](/guides/docs-mcp)            | `https://docs.lightdrift.ai/mcp`      | None. Public documentation requires no account, API key, or OAuth login.                                                     |

Both MCP servers use Streamable HTTP. Name them separately, such as `lightdrift` and `lightdrift-docs`. An Images MCP OAuth session does not configure the API key used by a standalone Python script.

## Find the symptom, then check the configuration

| Symptom                                                           | Next check or fix                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your REST script has no API key available                         | Supply `LIGHTDRIFT_API_KEY` to the process that runs the script, or use the hidden prompt below. A variable set in another terminal or a developer laptop may not be available to your deployed worker. Restart that process after changing its secret configuration. |
| An Images MCP connection reports authentication required or `401` | Complete the client's sign-in again. If using a key, check that it is active and sent as `X-API-Key`; use the [client-specific setup](/guides/images-mcp#choose-your-client).                                                                                         |
| Images MCP browser sign-in fails or loops                         | Open the sign-in link in your normal browser. Confirm your client supports OAuth; if it cannot complete OAuth, use a key only if it supports custom headers.                                                                                                          |
| No image tools appear                                             | Check the Images MCP URL, enable the server, and reload the connection or restart the client. Confirm remote Streamable HTTP support. Look for `search_images`, `find_similar_images`, and `get_image`.                                                               |
| The agent returns documentation instead of images                 | Add Images MCP as a separate server. Docs MCP searches documentation; it does not search the image library.                                                                                                                                                           |
| Docs MCP asks for a Lightdrift key or sign-in                     | Check for the exact Docs MCP URL above and remove image-server authentication headers from that connection. No Lightdrift login step is needed.                                                                                                                       |
| Images MCP reports `402` or insufficient credit                   | Check the account's [billing page](https://lightdrift.ai/dashboard/billing). A key uses its owning account's credit; changing connection syntax does not add credit.                                                                                                  |
| Images MCP reports `429` or a rate limit                          | Reduce concurrent searches and respect a returned retry delay. Check [plans and limits](/guides/plans-and-limits); do not rotate credentials to work around a limit.                                                                                                  |

The numeric symptoms above are documented in the [Images MCP troubleshooting reference](/guides/images-mcp#troubleshooting). For a REST failure, inspect the actual HTTP status and response in your private development environment rather than assuming every failure is authentication. Empty results or a degraded ranking response also do not, by themselves, identify a credential problem.

## Configure credentials without sharing them

Create or manage a key in [API keys](https://lightdrift.ai/dashboard/api-keys). Keep it in your backend secret manager or private client configuration. Do not put it in browser-delivered code, a shared project configuration, a public repository, screenshots, or support messages. Environment variables are one way to pass a secret to a process; they are not a reason to dump that process's environment into logs.

For MCP, follow the canonical [Images MCP setup](/guides/images-mcp#use-an-api-key-instead-of-sign-in). Placeholder keys in configuration examples must be replaced only in private storage. If a key has been exposed, revoke it in the dashboard and update the affected clients with a replacement.

## Verify with one REST request

First check your account entitlement and [current search pricing](https://api.lightdrift.ai/v1/pricing). As checked September 26, 2026, a successful search costs \$0.005. This example sends **one potentially billable search**, without retries. It does not establish free credit. Listing MCP tools instead checks tool availability without running a paid image search, but does not prove a search will succeed.

Save this as `check_lightdrift.py` and run `python3 check_lightdrift.py` in a terminal. It uses only the Python standard library, reads `LIGHTDRIFT_API_KEY` if supplied, and otherwise prompts without echoing the key. It prints no credential, request headers, or response body.

```python theme={null}
import getpass
import json
import os
import urllib.error
import urllib.request

key = os.environ.get("LIGHTDRIFT_API_KEY") or getpass.getpass("Lightdrift API key: ")
if not key.strip():
    raise SystemExit("No API key supplied; no request sent.")

payload = {
    "query": "coastal lighthouse at dusk with room for a headline",
    "k": 1,
    "experiment": "lig129_auth_check_v1",
}
request = urllib.request.Request(
    "https://api.lightdrift.ai/v1/search",
    data=json.dumps(payload).encode("utf-8"),
    headers={"X-API-Key": key, "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        result = json.load(response)
        print("HTTP", response.status)
        print("Query ID:", result.get("query_id"))
        print("Candidates:", len(result.get("results", [])))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, "— check your private response and account settings.")
except (urllib.error.URLError, TimeoutError):
    print("Connection failed or timed out; completion is unknown. Check usage before retrying.")
```

A successful response with a query ID verifies this REST request, not your separate MCP connection or future requests. Zero candidates is not proof of authentication failure. After an uncertain timeout, check account usage before repeating the search: a repeat can charge again. A successful public pricing-page fetch does not verify your API key.

## Continue with a real workflow

Use the [runnable terminal walkthrough](https://github.com/JacksonHolland/lightdrift-claude-plugin/tree/main/examples/terminal-walkthrough) to inspect presentation or itinerary requests without a key. Its dry-run makes no search calls; live execution is a separate step that consumes search entitlement. Return to the [REST quickstart](/quickstart), [Images MCP setup](/guides/images-mcp), or [Docs MCP setup](/guides/docs-mcp) for the connection you use.

Before placing any returned image in a product, check its source page, subject, license conditions, and required attribution. Preserve source links and credits through export. Returned rights metadata is a source declaration, not clearance for every use; see [Rights answers](/guides/rights).

[Create an account to try your first request](https://lightdrift.ai/sign-up?utm_source=docs\&utm_medium=guide\&utm_campaign=lig129_auth_check_v1\&utm_content=authentication-troubleshooting).