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.

What is the API Key Setup Documentation Builder?

Generate API key documentation covering where to generate the key, how to pass it in requests (header, bearer, or query), security best practices, rotation, and rate limits. Includes a live cURL example and exports as Markdown. It runs free in your browser on Gera Tools, with nothing uploaded.

API Key Setup Documentation Builder

Name: API Key Setup Documentation Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

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.

The three auth schemes compared

Authorization: Bearer — the standard for RESTful APIs that follow OAuth2 conventions. Use this when your key is functionally a long-lived token. Compatible with most API clients and SDKs without special configuration.

Custom header (X-API-Key) — common for non-OAuth APIs. Slightly more explicit than Bearer about the fact that this is an API key rather than a user token. Requires any HTTP client to set a custom header, which all can do but some developer tools make slightly harder than standard Authorization headers.

Query string — the least preferred option. The key appears in the URL, which means it can be:

Logged in server access logs
Stored in browser history
Captured in referrer headers when following a redirect
Visible in analytics tools

Use query-string auth only when the calling environment cannot set HTTP headers (some webhook systems, very old clients). Always mark it as deprecated in your docs and provide a migration path.

What the generated docs include

Where to get the key — link to your dashboard or API console with a sentence on what permission level is needed.
How to send it — the exact header or parameter with a cURL example using a YOUR_API_KEY placeholder.
Security section — environment variable storage, no source-control commits, no client-side bundles, no logging.
Test vs live keys — if your API uses prefixed keys (e.g., sk_test_ vs sk_live_), say so and explain what each can access.
What a failure looks like — document the 401 Unauthorized response body so developers can distinguish auth failures from network errors.
Rate limits — the sustained limit, burst, window, and what a 429 response looks like.
Rotation procedure — generate new key, update deployment, verify, revoke old key. Without this, a leaked key forces downtime.

Tips and example

Show the key in requests using a placeholder like YOUR_API_KEY, never a real-looking value — fake keys that look plausible confuse developers into trying to use them. Always document what a rejected key looks like so developers can tell auth failures apart from network problems immediately rather than filing a support ticket.