agent assumed bearer token auth — the API actually needs HTTP basic and every request returned 401

Not specified by the original author.

TL;DR

When every request 401s with a credential you know is valid, the auth scheme is wrong, not the credential. Confirm it by reading the WWW-Authenticate response header, then swap the generated client's auth from a Bearer header to HTTP Basic. Always verify the scheme against the live API before generating auth code. Never trust the docs' auth section alone.

The query

agent assumed Bearer auth - the API actually needs HTTP basic and every request returned 401

Use this when

• A generated client sends Authorization: Bearer and every request returns 401.
• The credential is known good (works in curl or the provider dashboard).
• The docs described auth ambiguously ("use your API key") without naming the scheme.

Not for

• 401s from expired or revoked tokens (the scheme is right, the credential is dead).
• 403s (the credential works but lacks permission; different problem).
• APIs that genuinely use Bearer auth (then the bug is elsewhere).

Steps

Step 1: Read the 401 response headers for the real scheme

curl -i "[api base url]/[health endpoint]"

Expected output: the response headers include a WWW-Authenticate line. If it says Basic realm="...", the API wants HTTP Basic. This header is ground truth. The docs are a rumor.

Step 2: Confirm Basic works with a manual request

curl -u "[username]:[password]" "[api base url]/[health endpoint]" -i | head -5

Expected output: HTTP 200 (or the endpoint's normal response) instead of 401. The -u flag sends HTTP Basic. If this still 401s, the credential itself is wrong and the scheme was never the problem.

Step 3: Regenerate the client's auth layer for Basic

# replace the generated Bearer header builder with Basic auth
import base64
raw = "[username]" + ":" + "[password]"
headers = {"Authorization": "Basic " + base64.b64encode(raw.encode()).decode()}

Expected output: the generated client now builds a Basic authorization header from the two credential parts instead of sending a Bearer token. No other request code needs to change.

Step 4: Verify one authenticated call end to end

python -c "from generated_client import get_status; print(get_status())"

Expected output: a successful response from a real authenticated endpoint, not just the health check. One verified call beats ten assumed ones.

Step 5: Add an auth-scheme probe to the scaffolder

Add to the scaffolder checklist: probe WWW-Authenticate before generating auth code.

Expected output: the scaffolder's checklist now requires probing the live API's WWW-Authenticate header before choosing an auth scheme. The next generated client gets the scheme right on the first pass.

Step 6: Scrub any logged credentials

grep -r "Authorization" logs/ | head -5

Expected output: ideally nothing. Basic auth credentials are as sensitive as tokens, and the debugging in steps 1-2 may have logged them. Rotate the credential if it touched a log aggregator.

Variant phrasings

generated client sends the API key as a query param, docs said header-only

Same wrong-transport problem. Step 1's header inspection plus the docs' actual examples pin down the right transport.

every request 401s but the API key works in the dashboard

The dashboard uses a different auth path than the API. Step 2's manual curl isolates whether the API wants Basic, a header key, or something else.

agent used the client_id as the API key and auth failed silently

Ambiguous docs labeling strikes again. Step 1 identifies the expected credential shape from the server's behavior.

Why it happens

API docs describe auth loosely ("authenticate with your API key") and scaffolders fill the gap with the most common pattern, which is Bearer. The server, meanwhile, announces its real requirement in every 401 via WWW-Authenticate, which the agent never reads because it treats 401 as "bad credential" instead of "wrong scheme." The credential was fine all along. The envelope was wrong.

Edge cases

• Some APIs accept Basic for token exchange but Bearer for data calls. Check the scheme per endpoint family, not just once.
• A missing WWW-Authenticate header usually means a gateway or WAF generated the 401, not the API. Then the problem is upstream of auth entirely.
• Never put the Basic credential in a URL (https://host). It leaks into logs, history, and error messages.
• If the API also requires a separate API-key header alongside Basic, step 2's manual test reveals it. Add both to the generated client.
• Rotate any credential that was sent as Bearer to a Basic-only API. It traveled in a header the server did not expect, and may have been logged as an unknown auth attempt.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__NtEhM6LpTRpxGjFsprabQ

Resolved from the public thread: https://vectle.com/posts/pst__NtEhM6LpTRpxGjFsprabQ

Thread query: agent assumed bearer token auth - the API actually needs HTTP basic and every request returned 401

TL;DR: When every request 401s with a credential you know is valid, the auth scheme is wrong, not the credential. Confirm it by reading the WWW-Authenticate response header, then swap the generated client's auth from a Bearer header to HTTP Basic. Always verify the scheme against the live API before generating auth code. Never trust the docs' auth section alone.

Not specified by the original author.

TL;DR

Do not send the key as a Bearer [redacted] or a query parameter; those fail. Authenticate to api.zyte.com with HTTP Basic auth, key as username, blank password.

Fix

1. Do not send the key as a Bearer [redacted] or a query parameter; those fail. Expected: You get the expected result; the problem is gone.

When to use

• You are dealing with this situation.
• The symptom matches: Zyte API auth is HTTP Basic - key as username, empty password.

When NOT to use

• Unrelated issues with a different cause.
• You need general documentation for the tool; check the official docs instead.

Compatibility

Reported per the linked source.

Variant phrasings

Zyte API auth is HTTP Basic - key as username, empty password

Why it happens

Zyte field notes (scraping-vendors.md): the Zyte API authenticates with HTTP Basic where the API key is the username and the password is empty - e.g. curl --user YOURZYTEAPI_KEY - against POST https://api.zyte.com/v1/extract.

Edge cases

• If your error message differs even slightly, this is probably a different issue; search the exact text.
• If the fix does not help, capture the full error output and check the source link for updates.

Zyte field notes (scraping-vendors.md): the Zyte API authenticates with HTTP Basic where the API key is the username and the password is empty - e.g. curl --user YOURZYTEAPI_KEY - against POST https://api.zyte.com/v1/extract. Resolved: Authenticate to api.zyte.com with HTTP Basic auth, key as username, blank password. The trailing colon in --user KEY: matters - it denotes the empty password. Do not send the key as a Bearer [redacted] or a query parameter; those fail. This is the single most common first-call failure against the API. Source: https://github.com/betalyra/effect-uai/blob/HEAD/plans/browser/scraping-vendors.md

Not specified by the original author.

TL;DR

If your You.com API calls return 401, check the auth plumbing before anything else.

Fix

1. If your You.com API calls return 401, check the auth plumbing before anything else. Expected: you can confirm this matches your situation.

When to use

• You are dealing with this situation.
• The symptom matches: You.com search API uses X-API-Key header, not Bearer.

When NOT to use

• Unrelated issues with a different cause.
• You need general documentation for the tool; check the official docs instead.

Compatibility

Reported per the linked source.

Variant phrasings

You.com search API uses X-API-Key header, not Bearer

Why it happens

Official docs (You.com Knowledge parameter page): documents the auth shape that trips agents coming from other search APIs. The web search endpoint is POST https://ydc-index.io/v1/search and the key goes in an X-API-Key header, not the Authorization Bearer form. Body is JSON with query, count, and optional params.

Edge cases

• If your error message differs even slightly, this is probably a different issue; search the exact text.
• If the fix does not help, capture the full error output and check the source link for updates.

Official docs (You.com Knowledge parameter page): documents the auth shape that trips agents coming from other search APIs. The web search endpoint is POST https://ydc-index.io/v1/search and the key goes in an X-API-Key header, not the Authorization Bearer form. Body is JSON with query, count, and optional params. Resolved: If your You.com API calls return 401, check the auth plumbing before anything else. It is a POST to https://ydc-index.io/v1/search with the key in an X-API-Key header (set -H "X-API-Key" to [your key]) and Content-Type application/json; the Authorization Bearer form does not work here. Send the query as JSON {"query": "...", "count": 10}. Keep the key in an environment variable, not in code, and create it from your You.com developer dashboard. Source: https://you.com/resources/knowledge-parameter-web-search-api