How do you stop OpenAPI definitions allowing API keys or credentials over cleartext HTTP?

Why cleartext HTTP is a design error in OpenAPI, not just a transport choice

OpenAPI should describe how an API is meant to be used, so allowing http:// server URLs or schemes for protected operations undermines the security model before a client is even built. The practical problem is not only accidental misuse, but also later reuse of the spec by generators, SDKs, gateways, and documentation that can normalize insecure transport.

For API descriptions, the safest pattern is to make HTTPS the only accepted transport for operations that carry credentials or session-bearing requests. That means the definition should never invite a client to send API keys, bearer tokens, or other secrets over cleartext HTTP, even in examples, staging variants, or alternate server objects.

A spec can be technically valid and still be operationally unsafe. If a request path, server entry, or example payload suggests that authentication material may travel over HTTP, the documentation becomes part of the exposure surface. API Security Guide is a useful reference point for the broader controls that should accompany a hardened API contract.

What to remove from the specification so insecure transport cannot reappear

Start by checking the server list, scheme declarations, and any example URLs in the OpenAPI document. The common failure is not a single obvious http:// endpoint, but a mixture of secure and insecure examples that leave room for tooling or developers to choose the wrong one.

Remove cleartext variants for any operation that depends on authentication, and avoid writing examples that place API keys in query strings, headers, or payloads without an explicit HTTPS context. If the spec is shared across environments, use separate secure server definitions rather than a single document that mixes safe and unsafe transport options.

That review should extend to generated documentation and code samples. A clean spec can be undermined later if a portal, mock server, or sample client republishes insecure URLs. OWASP API Security Top 10 is the right external baseline for reviewing API transport, authentication, and exposure risks together, not as separate problems.

How to keep insecure transport out of reviews and automation

The most reliable control is validation at the point where the specification is reviewed or generated, not after it has already been published. Treat insecure transport as a linting and release-blocking issue: if the spec contains http:// where credentials might be used, the build should fail.

That validation should inspect more than the server object. Review example requests, default values, autogenerated snippets, and any documentation templates that might quietly reintroduce cleartext transport. In practice, many teams fix the main schema but forget the examples, which is where developers often copy the pattern from.

When the API lifecycle is already mature, align the rule with your security standards for API consumption, authentication, and secret handling so it is enforced consistently across repos and environments. OWASP Cheat Sheet Series is a practical companion when you need implementation-level guidance on secure defaults and defensive review habits.

Risk and Threat Considerations

Cleartext transport creates an avoidable exposure window for credentials, session material, and API keys, especially when documentation is reused across teams, tools, and environments. The risk is amplified because OpenAPI is often consumed automatically, so a small mistake can scale into many insecure clients or copies of the same bad pattern.

Failure mechanism: An insecure server URL or example request is accepted into the spec, then copied into generated docs, SDKs, tests, or integrations, allowing sensitive requests to be made over HTTP.

Impact: Attackers or intermediaries can observe or manipulate authentication material, leading to credential theft, request tampering, unauthorized API use, and downstream compromise of dependent systems.

Practitioner Guidance

What to verify: Confirm that every server URL, example request, and autogenerated snippet uses HTTPS for authenticated flows, and reject any spec change that reintroduces cleartext transport in a sensitive path.

Decision rule: If an operation needs an API key, token, or any credential material, treat HTTP as a release blocker, even if the endpoint is only intended for internal or test use.

Common mistake: Teams secure the production server URL but leave insecure examples in the spec, then assume the documentation is safe because the live endpoint is not.

Practitioner takeaway: The control is strongest when you enforce HTTPS as a spec-level invariant and validate the rendered documentation and generated artifacts with the same standard.

Related resources from NHI Mgmt Group

• What breaks when agents use long-lived API keys or shared credentials?
• How should security teams choose between API keys, Device Flow, and Client Credentials for CLI apps?
• How should security teams handle exposed API keys and service credentials?
• Why do stolen API keys and login credentials matter more in AI-driven attacks?