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.

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