The OpenAPI Security Mistake That Makes Your Auth Invisible
Your API requires a bearer token. Your gateway enforces it. Your tests pass. And yet, your OpenAPI file says nothing about authentication which means every tool that reads your spec thinks those endpoints are public. Th
Your API requires a bearer token. Your gateway enforces it. Your tests pass. And yet, your OpenAPI file says nothing about authentication which means every tool that reads your spec thinks those endpoints are public.
This is one of the most common and most overlooked spec-level security issues. It doesn't break your application, so it never shows up in testing. But it misleads code generators, contract tests, and security scanners into treating protected endpoints as open ones.
Here's how to spot it, and how to fix it.
The Problem: No security Block on a Sensitive Endpoint
In OpenAPI, authentication is declared with the security keyword, either at the global level or per-operation. If an endpoint that returns user data or performs a write has no security definition, the spec is effectively declaring that endpoint as unauthenticated.
β What this spec says: this endpoint is public
paths:
/users/{id}:
get:
summary: Get user profile
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: User profile
Nothing here is syntactically wrong. The spec is valid OpenAPI. But it tells any consumerβincluding a code generator or a gateway configured from the specβthat this endpoint needs no credentials.
Why It Happens (and Why It's Easy to Miss)
There are three common reasons this shows up in real codebases:
1. The security scheme is defined globally, but the endpoint overrides it accidentally.
If you have a global security block but a specific operation includes security: , that operation is explicitly marked as public. This is easy to introduce by copy-pasting a template for a health-check or login endpoint.
2. The spec was written before auth was added.
The endpoint started as a prototype with no auth. Auth was added at the gateway or middleware layer later, but the spec was never updated.
3. The framework generated the spec without security annotations.
Some frameworks auto generate OpenAPI files and don't include security declarations unless you explicitly annotate the route. The runtime enforces auth via middleware, but the generated spec doesn't reflect it.
In all three cases, the runtime behavior and the documented contract disagree. That gap is the problem.
The Fix: Declare Security Explicitly
Define the security scheme once, then reference it on every operation that requires auth.
β Define the scheme globally
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
β Apply it globally...
security:
- bearerAuth: []
paths:
/users/{id}:
get:
summary: Get user profile
# ...inherits global security
If you need a public endpoint (like a login or health check), override it explicitly so the intent is visible:
paths:
/health:
get:
summary: Health check
security: [] # β
Explicitly public, not accidentally public
The difference between "no security block" and security: [] matters. The first is ambiguous; the second is a deliberate declaration.
How to Check Your Own Spec
You can do this manually: search your YAML for security: and confirm that every operation returning sensitive data or performing writes either inherits a global security block or defines its own.
But manual review gets tedious, especially with large specs where security schemes are defined in one place and referenced in dozens of operations. This is exactly the kind of check Cloakwave automatesβyou upload your OpenAPI or Swagger file, and it flags endpoints that appear to lack authentication declarations, along with other spec-level issues like unbounded schemas and credentials in query parameters.
If you want to run it against your own spec, you can try it here: https://cloakwave.io
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.