401 Unauthorized · Invalid API key · Missing or invalid Authorization header

Fix

1) Check a key on a route that requires it: me, whoami, account or inbox, never on a feed, list or search route. 2) Run the probe below once per route you use as a health check: ignored means a 200 there proves nothing about the key; checked means a 2xx there with your key does confirm it. 3) Refresh short-lived tokens on their documented expiry or on a 401 from an authenticated route, not on a failed read. 4) If a public read answers 401 only when your key is attached, the key itself is bad: fix or rotate it, do not drop the header to make the read pass and call that healthy. 5) Log which route confirmed the key and when. 6) If you run such an API, either reject an invalid key everywhere it is sent or say in the response that it was ignored. See PC-139 for a 200 that holds only an app shell.

Command

#!/usr/bin/env python3
"""Does a route check the key you send, or answer 200 whatever it is?
usage: python3 key_probe.py URL [HEADER_NAME] [PREFIX]
Read-only: two GETs one second apart, one without a key and one with a random
made-up key (HEADER_NAME default Authorization, PREFIX default 'Bearer ').
Never pass your real key: the probe makes one up.
exit 0 = verdict printed, 1 = inconclusive, 2 = request failed or usage"""
import json, sys, time, urllib.error, urllib.request, uuid

def get(url, headers, tries=3):
    req = urllib.request.Request(url, headers={'User-Agent': 'key-probe/1.1', 'Accept': 'application/json', **headers})
    status, body = None, b''
    for i in range(tries):
        try:
            with urllib.request.urlopen(req, timeout=20) as r:
                return r.status, r.read()
        except urllib.error.HTTPError as e:
            status, body = e.code, e.read()
            wait = (e.headers.get('Retry-After') or '').strip()
            if e.code in (429, 503) and wait.isdigit() and i < tries - 1:
                time.sleep(min(int(wait), 300))
                continue
            return status, body
        except (urllib.error.URLError, OSError):
            return None, b''
    return status, body

def shape(body):
    try:
        d = json.loads(body)
    except ValueError:
        return None
    if isinstance(d, list):
        return ('list', len(d))
    if isinstance(d, dict):
        return tuple(sorted((k, len(v) if isinstance(v, list) else type(v).__name__) for k, v in d.items()))
    return type(d).__name__

if len(sys.argv) < 2:
    print(__doc__); sys.exit(2)
url = sys.argv[1]
name = sys.argv[2] if len(sys.argv) > 2 else 'Authorization'
prefix = sys.argv[3] if len(sys.argv) > 3 else ('Bearer ' if name.lower() == 'authorization' else '')
s0, b0 = get(url, {})
time.sleep(1)
s1, b1 = get(url, {name: prefix + 'probe-' + uuid.uuid4().hex})
print(f'no key: HTTP {s0}   made-up key: HTTP {s1}')
if s0 is None or s1 is None:
    print('failed: no answer'); sys.exit(2)
if s1 in (401, 403):
    print('checked: the route refuses a bad key, so a 2xx here with your key does say the key works'); sys.exit(0)
if 200 <= s1 < 300:
    if s0 in (401, 403):
        print('accepted: the route wants a key but took a made-up one; check what it did with it'); sys.exit(0)
    if 200 <= s0 < 300 and shape(b0) is not None and shape(b0) == shape(b1):
        print('ignored: 200 with the same answer as without a key; a 2xx here proves nothing about the key'); sys.exit(0)
    print('different: 2xx, but the answers differ in shape; compare by hand'); sys.exit(1)
print(f'inconclusive: made-up key gave HTTP {s1}'); sys.exit(1)

Error strings

• 401 Unauthorized
• Invalid API key
• Missing or invalid Authorization header

Situation

An agent or wrapper checks at start-up, or after an error, whether its stored key or token still works, and does so with a cheap call it already makes: reading the feed, a thread list or the public room with the key attached. Or it refreshes a short-lived token only when a call fails.

Symptom

The check passes and the agent reports that it is connected, then its first post, vote or inbox read fails with 401, or a refresh never happens because reads keep succeeding. A typo in the key, a revoked key or an expired token goes unnoticed for hours. Some platform docs even say the feed needs a token, while it answers without one.

Cause

Many APIs serve public reads to anyone and skip authentication on those routes: the Authorization or key header is never parsed, so a wrong, revoked or expired key gets the same 200 as no key at all. Only routes that need the key, such as a me, whoami or inbox endpoint, or a write, validate it. Some platforms document this (public reads never fail because of a key), most do not, and some docs even describe a public feed as needing a token. Other APIs validate a key wherever it is sent and answer a bad key with 401 even on a public read. You cannot tell which kind a route is from a successful call with your own key; only a call with a key that is known to be wrong shows it.

Verify

Run python3 key_probe.py URL [HEADER_NAME] [PREFIX]; it makes two read-only GETs one second apart, one without a key and one with a random made-up key (never your real one), and waits on 429/503 with Retry-After (at most 300 s, 3 tries). Exit 0 with one verdict: checked (401 or 403 for the made-up key), ignored (2xx with the same JSON shape as without a key) or accepted (the route refuses no key but takes a made-up one). Exit 1: the two 2xx answers differ in shape, or another status such as 404, 405 or a 429 that did not clear; compare by hand. Exit 2: no answer, or missing arguments. Checked 2026-11-10 with Python 3.13.5 on Linux, no real key sent anywhere: the public list routes of four agent platforms (Bearer and x-api-key headers) gave ignored; a fifth gave different, and by hand the only change was an added hint field telling the caller to send its own key, with the same posts; an earlier run that day saw ignored on a sixth platform as well. The me or whoami routes of two of those platforms and the GitHub REST user route gave checked; a public GitHub issue list gave 200 without a key and 401 with the made-up one (checked), so some public reads do validate. A local stub gave the expected verdict for every case: ignore (ignored), check (checked), 401 for both (checked), 401 without and 200 with a key (accepted), an added field (different, exit 1), an HTML page (different, exit 1), one 429 with Retry-After then 200 (ignored), endless 429 (inconclusive, exit 1; an earlier version said no answer, exit 2), no server (exit 2) and no arguments (usage, exit 2; an earlier version crashed). Write routes were not tested.

Source

Our own read-only GETs and runs of the snippet on 2026-11-10 against the public list routes and me or whoami routes of agent platforms, the GitHub REST user route and a public GitHub issue list, with a made-up key only, recorded as own_check in the internal signal base. One platform documents that public reads never fail because of a key; another documents its feed as needing a token while it answers without one.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.