Notifications
Clear all
Topic starter
01/08/2026 10:51 pm
TL;DR: OpenAPI Specification documentation helps teams describe endpoints, parameters, and authentication, but Salt argues it often diverges from production reality, leaves shadow APIs undiscovered, and cannot stop logic abuse or attacker iteration. Schema validation alone is not a security boundary when documentation is incomplete, stale, or too broad.
NHIMG editorial — based on content published by Salt: OpenAPI documentation and API security analysis
By the numbers:
- OAS documentation noted 2 parameters and we found 27.
Questions worth separating out
Q: How should security teams use OpenAPI in API governance without overtrusting it?
A: Use OpenAPI as a discovery and validation aid, not as proof that the live service is safe.
Q: Why do incomplete API specifications create security risk?
A: Incomplete specifications leave defenders validating the wrong surface.
Q: What do teams get wrong about schema-based API security?
A: Teams often mistake syntactic validation for security enforcement.
Practitioner guidance
- Reconcile live APIs against the contract continuously Compare OpenAPI definitions to observed production traffic and alert on undocumented endpoints, missing parameters, and auth method changes before policy decisions are made on stale data.
- Use schema validation only where contract accuracy is proven Apply strict validation to low-risk interfaces with stable contracts, but require compensating monitoring and authorization checks where the OpenAPI file has known drift or incomplete coverage.
- Add logic-aware controls around high-risk endpoints Pair schema enforcement with business-rule validation, session context checks, and authorization testing so attackers cannot bypass controls by sending technically valid but contextually abusive requests.
What's in the full article
Salt's full analysis covers the operational detail this post intentionally leaves for the source:
- Examples of how schema validation behaves when undocumented parameters or endpoints appear in production.
- The vendor's explanation of strict versus loose validation trade-offs in real API environments.
- Operational guidance on using OAS as a schema for security tooling without blocking legitimate traffic.
- Additional detail on how API documentation gaps affect discovery, approval, and exposure analysis.
👉 Read Salt's analysis of why OpenAPI falls short as an API security control →
OpenAPI documentation and API security: where do controls break down?
Explore further
01/08/2026 10:59 pm
OpenAPI drift is a governance problem, not just a documentation problem. The article shows that an API contract can exist while the production service has already moved on. That means security reviews are being performed against an artefact, not the live access surface. For IAM and PAM teams, the same issue appears when entitlement records lag behind service reality. The practitioner conclusion is that contract accuracy must be treated as a control objective, not a documentation preference.
A question worth separating out:
Q: How can organisations tell whether OpenAPI documentation is trustworthy enough for enforcement?
A: They should compare documentation to live traffic, review how often contracts lag behind releases, and measure how many endpoints or parameters appear outside the specification. If the live environment regularly diverges from the file, the documentation should not be used as the primary enforcement source.
👉 Read our full editorial: OpenAPI documentation falls short as an API security control
