Secrets in OpenAPI and Swagger Specs: How API Documentation Exposes Live Credentials

Your API Documentation Is Probably a Credential Risk

OpenAPI (formerly Swagger) specs are the backbone of modern API documentation. They're generated, committed, shared, and sometimes published — often without anyone pausing to ask: does this file contain real secrets?

The answer, surprisingly often, is yes. API keys end up in example request blocks. Bearer tokens get hardcoded into securitySchemes. Internal service URLs with embedded credentials appear in servers entries. And because these files look like documentation rather than code, they escape the scrutiny that source files receive.

This article walks through exactly how credentials leak through OpenAPI and Swagger specifications, where to look for them, and the concrete steps to prevent it — whether you're a solo developer, an engineering lead, or an MSP managing multiple client environments.

How Credentials Get Into OpenAPI Specs in the First Place

There are three common paths:

• Auto-generation from a live environment. Many frameworks (FastAPI, Springdoc, NestJS, etc.) auto-generate OpenAPI specs by reflecting on your running application. If your app is configured with real credentials at generation time, those credentials can bleed into example values, default headers, or server definitions.
• Developer convenience during testing. Developers fill in real tokens when writing example requests to make the interactive Swagger UI actually work. The convenient thing becomes a permanent fixture when the spec is committed.
• Templating and copy-paste from internal tools. Internal API specs get forked from a working example. The working example had real credentials. Now every fork does too.

The Specific Places to Audit in an OpenAPI File

If you're auditing a openapi.yaml or swagger.json manually, focus on these locations:

1. servers Object

The servers block defines base URLs. It's possible — and we've seen it — for connection strings or authenticated endpoints to appear here:

servers:
  - url: https://api.internal.example.com
    description: Production
    # Sometimes developers add credentials in URL form:
    # url: https://apikey:s3cr3t@api.internal.example.com

Credentials embedded in URLs are easy to miss because they look like configuration, not secrets.

2. securitySchemes and security Blocks

These define how authentication works. The definitions themselves are fine — but watch for any field that includes an actual key value rather than a placeholder:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      # A placeholder is fine. A real key value is not.

3. examples and x- Extension Fields

The examples block in request/response schemas is the single highest-risk location. Developers routinely paste real tokens here so that the Swagger UI "Try it out" feature works in staging or production:

requestBody:
  content:
    application/json:
      examples:
        default:
          value:
            api_key: "sk-live-abc123realtoken..."  # ← this is the problem

Custom extension fields (x- prefixed) are equally risky because they're often undocumented and undersearched.

4. parameters with default Values

Header and query parameter definitions can include a default field. If someone set the default to a real credential for convenience, it's now in your spec:

parameters:
  - name: Authorization
    in: header
    schema:
      type: string
      default: "Bearer eyJhbGci..."  # ← never do this

Why Published Specs Are Especially Dangerous

OpenAPI specs are frequently:

• Committed to public GitHub repositories alongside the codebase
• Served directly from a public-facing endpoint (/openapi.json, /swagger.json, /docs)
• Exported and shared with partners or customers
• Stored in API portals (Postman, Readme.io, Stoplight) that have their own access control models

Each of these distribution paths multiplies the exposure surface. A credential that lives in your repo's openapi.yaml is already one public-repo accident away from being indexed by automated scanners that continuously harvest secrets from GitHub.

And unlike a leaked .env file, which most teams would spot in a PR review, an OpenAPI spec with a hardcoded example token looks like a documentation artifact — exactly as intended. That's what makes it dangerous.

The Compliance Angle: SOC 2 and HIPAA

If your organization is pursuing SOC 2 Type II or handles protected health information under HIPAA, credential exposure in documentation files is an auditable problem, not just a hygiene issue.

SOC 2's CC6 (Logical and Physical Access Controls) cluster requires evidence that credentials are managed and not exposed in unauthorized contexts. An auditor who finds a live API key in your committed OpenAPI spec will flag it — and rightfully so. HIPAA's Technical Safeguard requirements around access controls carry the same implication: a key capable of accessing PHI should never appear in a documentation file.

Secret scanning coverage needs to include documentation artifacts, not just application source files.

Concrete Steps to Fix This

1. Grep your spec files right now. Run the following against any .yaml, .json, or .yml file that looks like an API spec:

   grep -rEi "(api[_-]?key|bearer|authorization|token|secret|password)\s*[:=]\s*['\"]?[A-Za-z0-9+/=_\-]{16,}" ./docs ./api

   This is a blunt instrument, but it catches a surprising number of real hits.

2. Replace all real credential values with clearly fake placeholders. Use values like YOUR_API_KEY_HERE, <token>, or REPLACE_ME. These are unambiguous, cannot be mistaken for real credentials, and won't trip up automated scanners with false positives.
3. Disable "Try it out" in Swagger UI for production specs. If you serve a live Swagger UI, configure it with supportedSubmitMethods: [] to disable the interactive request feature entirely, or serve a separate spec with sanitized examples for public consumption.
4. Add OpenAPI file patterns to your secret scanning rules. Most secret scanners default to scanning source code extensions. Explicitly include *.yaml, *.yml, *.json, and common documentation paths (/docs/, /api/, /swagger/).
5. Treat spec generation as part of your CI pipeline — with validation. If specs are auto-generated, add a CI step that scans the generated output before it's committed or published. Never commit a generated spec without reviewing it first.
6. Audit your API portals. If you've uploaded specs to Postman workspaces, Readme.io, or Stoplight, review the access settings. A "private" workspace shared with a contractor is not a secure credential store.

Rotate Any Key That Appeared in a Spec

If you find a real credential in an OpenAPI file, assume it's compromised. Rotation is the only safe response — not deletion, not making the repo private. Check your version control history too: even if you remove the key from the current file, it may exist in dozens of past commits.

For a broader picture of what else might be exposed across your codebase and configuration files, run a free GhostCred scan — it covers API keys, tokens, and IAM misconfigurations across your repos and .env files in around 60 seconds, with findings mapped to SOC 2 and HIPAA controls.

The Takeaway

OpenAPI and Swagger specs occupy a blind spot in most teams' security posture. They're treated as documentation, but they're files — files that get committed, shared, and published, and that can contain credentials every bit as live and dangerous as anything in your application source.

The fix is not complex: audit your specs, replace real values with explicit placeholders, include spec files in your secret scanning coverage, and make credential hygiene part of your documentation workflow, not an afterthought. The same discipline you apply to your .env files should apply everywhere a credential could be written down — and API documentation is a place credentials get written down far more often than most teams realize.