The documented `hd_` API-token prefix contradicts the only token we have observed

[zfarrell]

The SDK teaches an hd_ prefix for the API token in its own source and README. The evidence says that prefix is wrong.

Where the claim lives

src/auth.rs:4           //! a long-lived `hd_` API token, it lands on
src/client.rs:16        //!     .api_token("hd_live_...")          // sent as the Authorization bearer
src/client.rs:104       /// Set the API token (e.g. `hd_live_...`). It is sent verbatim as the
examples/quickstart.rs:12   //! ... you pass your `hd_...` API token and
examples/quickstart.rs:19   //! export HOTDATA_API_KEY="hd_live_..."
README.md:39            Your API token (prefixed `hd_`) is the only credential you need.
README.md:47            .api_token("hd_your_api_token")

src/client.rs:16 and :104 are public doc comments, so this ships to docs.rs. The README occurrences at :39 and :47 are the two that assert the prefix as fact; :89, :218, and :279 carry it as placeholder text, and the test fixtures (hd_opaque, hd_from_env, …) are arbitrary strings that don't matter either way.

The evidence

www#365 (F38) records that the token which authenticated every call in the docs audit was 64 hex characters with no prefix, and that hd_ appears nowhere else in the docs.

So one real, working credential does not have this prefix. What is not established:

• whether 64-hex-no-prefix is the only issuable format, or one of several (a hd_live_/hd_test_ environment split, if it exists at all, was never observed);
• whether the prefix was ever correct and has since changed;
• whether the format is a stable contract worth documenting at all.

That's why this is filed rather than patched: the fix isn't "delete hd_", it's "state the format monopoly actually issues, or stop claiming one."

Why the docs site isn't the bug

The docs site was faithfully echoing the SDK — the audit found the hd_ claim on hotdata.dev and traced it back here. www PR #374 has already replaced the claim on the site with a neutral placeholder, which is correct either way: it stops teaching a wrong format without asserting a specific replacement.

What to do

1. Establish the actual API-token prefix and format from the issuing service (monopoly), including whether there is an environment split.
2. Update src/auth.rs, the two public doc comments in src/client.rs, examples/quickstart.rs, and the two asserting README lines to match — or make them format-neutral if the format isn't a contract.
3. If the format is a contract, state it once and link it rather than restating it in six places.

Related

• Split out of query and query_preview cannot pass a database id #118 while closing it — that ticket recorded this as a side finding.
• www#365 (F38) — the observed 64-hex token.
• www#374 — the docs-site half, already neutralised.