API Reference DocumentationLesson 3.4

Writing authentication and security documentation

API key documentation, OAuth 2.0 flow documentation, Bearer token usage, token scopes, token expiry, security headers, rate limiting documentation

Authentication Documentation

Authentication documentation must be exhaustive. A developer who can't authenticate can't use anything else in your API. Every auth failure is a blocker, so documentation must pre-empt every common mistake.

API Key Authentication

## Authentication

All requests must include your API key in the Authorization header:

```bash
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Getting your API key:**
1. Log in to your dashboard at app.example.com
2. Navigate to Settings → API Keys
3. Click Generate New Key

**Important:**
- Store keys in environment variables, never in code
- Keys expire after 90 days
- Rotate compromised keys immediately from the dashboard

Documenting Scopes

| Scope         | Access Level                          |
|---------------|---------------------------------------|
| read:users    | Read user profiles and lists          |
| write:users   | Create and update users               |
| delete:users  | Delete users (requires admin role)    |

Rate Limiting

Document your rate limits in the authentication section, not buried in a footnote. Include the response headers developers can use to track usage:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1677649200