Authentication is the first real barrier every API consumer hits, and undocumented auth setup stops adoption cold. A .env.example that lists API_KEY= without explaining what that key is, where to get it, or how to include it in requests leaves developers at a dead end. For OAuth or JWT flows, missing documentation means developers either skip auth entirely in development or implement it incorrectly, creating security exposure. iso-25010:2011 analysability and user-experience quality both depend on auth documentation that includes the full flow: obtain credential, include in request, handle failure.
High because undocumented authentication makes the API unusable in practice — developers cannot make a single authenticated request without guessing the credential format, and incorrect implementations produce silent security gaps.
Add an Authentication section near the top of the docs — before any endpoint reference — that covers all three steps: obtain, use, and handle failure:
## Authentication
All requests require a Bearer token in the `Authorization` header.
1. Sign up at [example.com/signup](https://example.com/signup)
2. Generate an API key in **Settings > API Keys**
3. Include it in every request:
```bash
curl https://api.example.com/data \
-H "Authorization: Bearer YOUR_API_KEY"
A missing or invalid key returns 401 Unauthorized. Expired tokens return 401 with {"error": "token_expired"}.
The section must be findable from the docs navigation or table of contents, not buried in an unrelated section.
ID: developer-documentation.api-reference.auth-docs
Severity: high
What to look for: If the project requires authentication (API keys, OAuth, JWT tokens, session cookies), check whether the documentation explains how to obtain credentials, how to include them in requests, and what happens when authentication fails. This includes both API authentication (for APIs/SDKs) and user authentication setup (for apps that integrate auth providers). Count all instances found and enumerate each.
Pass criteria: Documentation explains: (1) how to obtain credentials (API key, OAuth app, etc.), (2) how to include credentials in requests (header format, SDK configuration), (3) what errors to expect on auth failure. Includes a working code example. At least 1 implementation must be confirmed.
Fail criteria: Project requires authentication but docs don't explain how to set it up, or docs mention "add your API key" without explaining the header format or where to get the key. Common pattern: .env.example lists API_KEY= but nothing explains what API key is needed or where to get it.
Skip (N/A) when: The project does not require any authentication -- it is a utility library, a static site generator, or a tool that operates without credentials.
Cross-reference: The endpoint-coverage check in API Reference verifies that endpoints requiring auth document the auth requirement inline.
Detail on fail: Example: "API requires Bearer token authentication but docs never explain how to obtain a token or what header to use" or "SDK constructor accepts apiKey but docs don't explain where to get one"
Remediation: Add an authentication section early in the docs:
## Authentication
All API requests require a Bearer token in the Authorization header.
1. Sign up at [example.com/signup](https://example.com/signup)
2. Generate an API key in Settings > API Keys
3. Include it in requests:
```bash
curl https://api.example.com/data \
-H "Authorization: Bearer YOUR_API_KEY"
If authentication fails, you'll receive a 401 Unauthorized response.