API Security Documentation — OAuth2, API Keys, Rate Limiting
Practice documenting API security schemes: API key authentication, OAuth2 flows, Bearer tokens, scopes, rate limiting, CORS, and security best practices in OpenAPI specs.
0 / 5 completed
1 / 5
How are security schemes defined and applied in OpenAPI 3.x?
OpenAPI security pattern: define in components/securitySchemes (e.g., BearerAuth, ApiKeyAuth, OAuth2), then reference by name at the global level (applies to all operations) or override per operation. An empty security array ([]) on an operation means that operation is public. This separation of definition from application keeps specs DRY and makes security auditing straightforward — reviewers can check all schemes in one place.
2 / 5
What is the correct OpenAPI vocabulary for documenting OAuth2 scopes?
OpenAPI OAuth2 scope documentation: under securitySchemes > YourOAuth2 > flows > authorizationCode > scopes: { 'read:orders': 'Read order history and status', 'write:orders': 'Create and modify orders', 'admin:users': 'Manage user accounts (admin only)' }. Then on each operation: security: [{ OAuth2: ['read:orders'] }]. Documenting scopes with clear descriptions helps consumers request only the permissions they need, following the principle of least privilege.
3 / 5
How should rate limiting be documented in an API specification?
Complete rate limit documentation: (1) In endpoint description: 'Rate limit: 100 requests per 15-minute window per API key.' (2) In response headers schema: X-RateLimit-Limit (total allowed), X-RateLimit-Remaining (remaining in window), X-RateLimit-Reset (Unix timestamp when window resets), Retry-After (seconds until retry allowed). (3) 429 response body with RFC 7807 format. (4) Burst limits vs. sustained limits if both apply. Undocumented rate limits cause surprise outages for consumers.
4 / 5
What is the difference between 'http' type with 'bearer' scheme and 'apiKey' type in OpenAPI security schemes?
http/bearer: Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... — typically a JWT with expiry and claims, issued via OAuth2 or an auth server. apiKey: X-API-Key: sk-abc123... or ?api_key=sk-abc123 — typically an opaque long-lived secret. Document apiKey location (header/query/cookie), the header name, and key rotation guidance. For bearer, document token expiry, refresh flow, and the issuer. Both should document what to do when the credential is compromised.
5 / 5
How should CORS (Cross-Origin Resource Sharing) be documented in an API specification?
CORS documentation matters for browser-based consumers. Document: Access-Control-Allow-Origin (list allowed origins or wildcard), Access-Control-Allow-Credentials (true if cookies/auth headers sent with credentials), Access-Control-Allow-Headers (custom headers your API accepts), Access-Control-Expose-Headers (custom headers your API exposes beyond CORS-safelisted ones like X-RateLimit-*), Access-Control-Max-Age (preflight cache duration). Include a note like: 'If you are integrating from a browser, contact support to allowlist your origin.' Undocumented CORS causes confusing integration failures.