Vol. I — The Argument
Documentation
is a decision
system.
Not a knowledge base. The difference is not what you write, it is what you make the reader do next. Below is the same technical content, restructured with that one question in mind.
Scenario 01 — API Authentication
The same content, written two different ways.
Same facts. Different intent.
The Knowledge Base
Authentication and Authorization Reference
This platform supports API key authentication, OAuth 2.0 with authorization code, client credentials, and implicit grant types, JWT bearer tokens with configurable signing algorithms, HMAC-SHA256 request signatures, mutual TLS for service-to-service scenarios, and SAML 2.0 for enterprise identity provider integration. Rate limiting is enforced per credential. Token expiration windows, rotation schedules, and permission scopes are configurable via the admin API or dashboard. For SDK-level implementation, see the language-specific guides in the developer reference.
The Decision System
Which authentication method is actually right for you?
If you are building a service that talks to another service with no human in the loop, use an API key. It is boring, it works, and you will not regret it. If you are building something where a real person logs in, use OAuth 2.0, specifically the authorization code flow for web apps and PKCE for anything mobile or CLI. JWT is worth the overhead in exactly one situation: a downstream service needs to read claims out of the token without calling back to validate it. If nothing in your system needs that, you do not need JWT. Start with the simplest thing that closes your threat model.
Section 03 — The Theory in Action
The live decision tree.
Answer two questions,
get a recommendation.