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.
Editorial analysis by NHI Mgmt Group, based on content published by Salt: “Is OAS Enough For API Security?”.
Key questions
Q: What breaks when OpenAPI specifications are missing or out of date for API security testing?
A: Security testing stops matching the real API surface.
Q: Why does schema validation fail against API abuse?
A: Schema validation checks structure, not intent.
Q: What are the signs that API documentation is drifting away from the real implementation?
A: The main signs are mismatched responses, undocumented fields or endpoints, custom code added to override generated specs, and tests that no longer reflect actual behavior.
Practitioner guidance
- Continuously reconcile the API inventory Compare the documented OpenAPI contract with live traffic, observed endpoints, and actual parameters so undocumented or changed interfaces are visible before review cycles close.
- Separate schema checks from authorisation checks Use validation for structure, but enforce authorisation, object access, and workflow controls at runtime so requests that fit the schema are still evaluated for intent and entitlement.
- Treat undocumented endpoints as active risk Escalate any endpoint, parameter, or response pattern that appears in production but not in the spec, because absent documentation means absent governance until proven otherwise.
Bottom line: OpenAPI helps teams document and validate APIs, but it does not prove the live service matches the contract.
Explore further
View Full Forum → | NHI Foundation Course → | Our Services → | Read the full analysis →
01/08/2026 10:59 pm
OpenAPI drift is a governance problem, not just a documentation problem. Once the live API diverges from the contract, every downstream control that depends on the contract inherits false confidence. Security teams then validate a model of the API instead of the API itself, which is precisely how shadow interfaces stay visible to developers but invisible to governance. Practitioners should treat contract drift as a first-class control failure.
A few things that frame the scale:
- Secrets management is a top five cybersecurity priority for only 33% of organisations, behind cloud security (45%), API security (42%), and endpoint security (36%), according to the 2024 State of Secrets Management Survey.
- 71% of organizations use third-party APIs, according to Gartner’s 2024 data.
A question worth separating out:
Q: How should teams govern APIs that are used by service accounts and automation?
A: Treat those API paths as part of the identity estate. Inventory the service accounts, tokens, and delegated applications that can reach sensitive endpoints, apply least privilege to each one, and retest whenever a workflow or payload changes. That prevents machine identities from inheriting broad access by default.
👉 Read our full editorial: OpenAPI documentation falls short as an API security control