OpenAPI lint: the missing security scheme that makes every endpoint look public

Pentrova processes a lot of OpenAPI specs, and the single most common pattern on production endpoints is a well-described API where every schema is accurate, every path is documented — and no operation has a security requirement attached. The scanner’s response is consistent: “no auth scheme declared, treat every operation as public.”

This post explains why that drift happens, why it is more than a documentation nit, and the one-block fix that closes it.

The mistake, in spec terms#

In OpenAPI 3, authentication is expressed in two places: a securitySchemes block under components that describes how a credential travels, and a security requirement that applies a scheme to the root or to individual operations. The common failure is having neither — or describing a scheme but never applying it:

# Drifted spec: no security requirement anywhere → every operation reads as public
paths:
  /invoices/{id}:
    get:
      summary: Get an invoice
      responses: { '200': { description: OK } }

# Hardened spec: scheme described AND applied
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
security:
  - bearerAuth: []

Why it is not just a documentation nit#

Usually a bearer token is enforced in the gateway, or an API key is expected in a header, but the spec never learned about it. That gap matters because the spec is not just docs — it is a contract that downstream tooling inherits:

• Client SDK generators produce clients that send no credential.
• Mock servers model the API as open, hiding auth bugs in integration tests.
• Contract tests validate against a public-by-default shape and pass when they should fail.
• Security scanners under-prioritise endpoints that are actually sensitive.

That last point matters for coverage. Pentrova uses the same lint pass internally to decide which endpoints to exercise under which auth mode, so an inaccurate spec directly reduces the coverage the platform can claim — the opposite of what you want from API Pentesting.

Catch it before it ships#

Pentrova’s free API Spec Linter runs this check locally in the browser — upload a spec, get an itemised report, and fix the drift before it affects the next integration. Running it in CI on every spec change keeps the contract honest, which is the same discipline as the CI-gated pentest runbook applied to API definitions.

The fix#

The fix is small: a securitySchemes block under components describing how each credential travels, plus a security requirement attached to the root (or to the specific operations that need a tighter policy). Apply the scheme where it belongs, regenerate clients, and the whole downstream chain — SDKs, mocks, tests, scanners — inherits the correct assumption.

Key takeaways#

• The most common OpenAPI mistake is describing an API perfectly but never applying a security requirement.
• A spec without security reads as fully public to every downstream consumer.
• The drift breaks SDKs, mock servers, contract tests, and reduces scanner coverage.
• Fix it with a securitySchemes block plus a security requirement; lint specs in CI to keep them honest.

FAQ#

Does a missing security block mean my API is actually unauthenticated? Not necessarily — auth is often enforced in the gateway. But every tool that reads the spec will assume the endpoints are public, which causes generated clients, mocks, and tests to behave incorrectly and hides real auth gaps.

Where should the security requirement go — root or per-operation? Apply a sensible default at the root and override per-operation only where a tighter or looser policy is genuinely needed (for example a public health check). A root default ensures nothing is accidentally left open.

Can I automate this check? Yes. Run the API Spec Linter in CI on every spec change so a drifted spec fails the build before it reaches client generators or your scanner.

Lint your spec now with the free API Spec Linter, or see how specs drive API Pentesting.