Authentication setup is documented
Why it matters
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.
Severity rationale
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.
Remediation
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.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the Developer Documentation Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · maintainability.analysability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from developer-documentation·automated