Document API authentication in OpenAPI 3.1: Bearer, API keys, OAuth 2, and mTLS without the usual mistakes
Most OpenAPI auth docs are subtly wrong: a scheme is defined but never applied, a token is modeled as a plain header, or OAuth scopes do not match the server. Here is how to document each mechanism correctly, combine them with AND/OR semantics, and mark public endpoints.


