Skip to content

docs(hub): document optional API keys - #26

Open
sefk wants to merge 1 commit into
devfrom
docs/api-keys
Open

sefk wants to merge 1 commit into
devfrom
docs/api-keys

Conversation

@sefk

@sefk sefk commented Nov 16, 2026

Copy link
Copy Markdown

Summary

The website's platform proxy now accepts optional API keys (website#143, part of website#142). This adds a how-to page for them and says on the home page that keys are optional. Anonymous access is unchanged, and the page says so.

The page covers:

  • Creating a key at /account/api-keys (shown once, up to 5 per account, delete to revoke, about a minute to take effect).
  • Sending it as Authorization: Bearer <key> or X-API-Key: <key>, never in the query string, and the 400 when both headers differ.
  • Where keys apply (/api/v1/*, /openapi.json, /codes, /mcp; not Studio).
  • Limits: anonymous 120 a minute on the API and 300 on MCP per address; keyed 600 and 600 per account, separate by surface, shared by all of an account's keys, higher on request.
  • Errors: 401 invalid_api_key (no fallback to anonymous) and 429 rate_limited with Retry-After and X-RateLimit-*.
  • MCP clients: developer clients and Claude custom connectors can send the key; ChatGPT connectors cannot.
  • Keeping the key secret.

Pages changed

  • content/hub/build/api-keys.md: new page, "Use an API key", under Build with the DFO.
  • hub.yaml: nav entry for the new page.
  • content/hub/index.md: the MCP connection paragraph and "Do I need an account?" now say keys are optional and link the new page.

Not in this PR

The API quickstart ("The API accepts requests without an API key.") and the MCP connect page ("No token is needed.", the HTTP 429 row) live in the apis and ai repositories (docs/guide/), which this build fetches. They need their own small PRs to say keys are optional and to link /docs/build/api-keys. This page links to both.

How verified

  • uv run ruff check ., uv run ruff format --check ., uv run pytest (819 passed).
  • pre-commit (mdformat, codespell, yaml) passes on the changed files.
  • uv run python scripts/build.py succeeds and the page is in the corpus and manifest.
  • lychee --config lychee.toml over the built corpus: 0 errors.
  • The anonymous rate-limit headers in the example come from a live call to /api/v1/graph/capabilities. The 429 example is from the website's local test run. A keyed call has not been run against production, because the feature is not deployed yet.

Coordination

Publish after website#143 is deployed, so the page does not describe a key page that does not exist yet. Part of DevelopmentFinanceObservatory/website#142.

Claude-generated draft.

🤖 Generated with Claude Code

https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf

Add a how-to page on API keys: create one on the account page, send it as
a bearer token or X-API-Key header, where it applies (API and MCP, not
Studio), per-account limits, and the 401 and 429 errors. Say in the home
page that keys are optional and link the new page from the MCP connection
paragraph and the account question. Add the page to the Build nav.

Part of DevelopmentFinanceObservatory/website#142.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant