Gateway modes: A and B, in full
2026-11-13
Gateway modes A and B, in full
The short version is in the welcome post;
this is the long one. The gateway is one OpenAI-compatible proxy in front of
Baidu Qianfan. Mode B (metered resale) was cancelled on 2026-11-13; what
remains is Mode A, plus the story of why B had to go — which is itself the
compliance lesson of this project.
Mode A — bring your own key (BYOK)
You hold a Qianfan key, you send it with each request, and the gateway adds
what a raw key does not have: gateway authentication (X-Gateway-Key), rate
limiting by subscription plan, usage metering, and one stable OpenAI-compatible
request shape across both Qianfan editions.
- The key is never stored on our side; it is forwarded as
Authorization: Bearer
(or X-Provider-Key) and used once.
- Key-edition validation is fail-closed: only keys registered in the gateway
registry are accepted for a given edition, so a domestic key cannot serve an
international request even by accident.
- Pricing is a flat subscription; there is no per-token markup on your key.
Mode B — metered resale (cancelled 2026-11-13)
Mode B was designed so customers would not each need their own Qianfan account:
you would use our international key pool and pay per token. It is withdrawn.
The reason is not technical: the only keys we actually hold are domestic-edition
keys, and serving overseas traffic with them would violate the cross-border data
rules this gateway exists to enforce (C2/S3). A compliance feature you cannot
operate compliantly is not a feature; it is a liability with a nice dashboard.
/intl/b is now rejected at the gateway on both editions with
403 mode_B_not_allowed_on_intl. The metering, billing, idempotency and
reconciliation machinery built for it stays in the codebase — tested and dormant
— so a real international key pool could revive the mode without a rewrite.
Why the path encodes everything
/cn/a/... is not documentation sugar. It makes the edition boundary visible
in every log line, every screenshot, and every incident review. The S3 block (no
domestic keys on international routes) is enforced by the same code that serves
the happy path — there is no flag to misconfigure, because the flag does not
exist.
Where the boundary shows up in practice
- Request: the path decides edition and mode; headers carry keys, not policy.
- Response: the gateway adds
X-Tokencoup-Statusonly when degraded; a normal
200 looks like the upstream shape, because we do not rewrite your body.
- Billing: Mode A subscription billing never shares a ledger scope with the
(dormant) Mode B machinery.
Pre-launch honesty
https://api.tokencoup.com currently answers 503 error.type=not_live at the
edge; the reference implementation runs locally and the full contract is in the
API reference. Mode A key registration opens with the
account system; until then, the contract is documented but not for sale. We
ship the honest state, including the parts that do not work yet — and the parts
we chose not to ship at all.