Should the key go in a header or the query string?

Prefer a header — either Authorization: Bearer or a custom header like X-API-Key. Query-string keys leak into server logs, browser history, and referrer headers, so they are the least safe option and should only be used when a header is impossible.

How do I tell users to store the key safely?

Tell them never to commit it to source control or ship it in client-side bundles. The key belongs in an environment variable or a secrets manager, read at runtime on the server. This builder includes that guidance in the security section automatically.

What should the rate-limit section say?

State the limit (for example 100 requests per minute), the window, and what happens when it is exceeded — typically a 429 response with a Retry-After header. Documenting this up front stops developers from treating throttling as an outage.

Should I document key rotation?

Yes. Explain how a user generates a new key and how long the old key keeps working during the overlap. Without a rotation story, a leaked key forces downtime, so a documented rotate-then-revoke flow is a security feature in itself.

What is the difference between an API key and a token?

An API key is a long-lived static secret that identifies the caller. A token (such as an OAuth access token) is usually short-lived and scoped. Many APIs use a key for simple server-to-server calls and tokens for user-delegated access; document whichever your API uses and do not mix the terms.

API Key Setup Documentation Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Make your auth docs the page developers never get stuck on

API key documentation is the first real thing a developer touches, and a confusing auth page kills integrations before they start. Good key docs answer four questions without ambiguity: where do I get the key, how do I send it, how do I keep it safe, and what are the limits. This builder produces all four — plus a copy-pasteable cURL example that matches the exact scheme you choose.

How it works

You pick an auth scheme and the tool generates a matching request example and a complete docs section:

Bearer:        Authorization: Bearer <key>
Custom header: X-API-Key: <key>
Query string:  ?api_key=<key>   (discouraged — leaks in logs)

The cURL example is built from your base URL and chosen scheme so it is correct, not generic. The security section is filled in with the non-negotiables — store the key in an environment variable, never commit it, never ship it client-side — and the rate-limit section uses your numbers to explain the 429 behaviour. Everything is plain Markdown ready for a docs site.

Tips and example

Show the key in requests using a placeholder like YOUR_API_KEY, never a real-looking value, so nobody copies a fake key and wonders why it fails. If your API distinguishes test and live keys, say so and prefix them clearly (for example sk_test_ vs sk_live_). Always document what a rejected key looks like — usually a 401 Unauthorized with a JSON error body — so developers can tell an auth failure apart from a network problem. A rotation note (“generate a new key, deploy it, then revoke the old one”) turns a leaked-secret panic into a routine operation.