DEV Community

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.

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

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.