How should teams handle API routes that appear in code but not in the spec?

Treat them as governance defects, not documentation gaps. If code and specification disagree, the security team does not have a trustworthy inventory, which means release decisions are being made against incomplete evidence. The right response is to reconcile source and spec before deployment and require a named owner for any endpoint that remains reachable.

Why code-only API routes are a governance problem

Routes that exist in code but not in the specification are not just a documentation mismatch. They create an inventory gap, which means reviewers, test teams, and approvers are reasoning over a system that is not fully described. That gap matters because access control, data exposure, and release risk are all judged against the inventory you think you have, not the one actually running.

When a route is missing from the spec, the practical failure is usually that no one owns its intended behavior, auth model, or data handling assumptions. The result is often inconsistent treatment across environments, with one team believing a path is internal-only while another can still call it in production. Teams should treat that as a control failure and reconcile the source of truth before the route is exposed.

If the route is intentionally real, the spec should be updated to describe it fully, including method, path, auth expectations, and any data sensitivity assumptions. If it is accidental, the code should be removed or disabled rather than left as an undocumented reachable surface. In both cases, the endpoint must have a named owner so it cannot persist as an orphaned control exception.

What has to be reconciled before release

The key decision is whether the code or the spec is wrong, because those two states require different remediation. A code-only route that is meant to ship needs specification parity so security testing, approval workflows, and consumers are all evaluating the same interface. A route that was left behind by refactoring, feature toggles, or partial deployment should be treated as stale attack surface until it is removed or formally accepted.

At minimum, teams should verify route inventory, ownership, authentication, authorization, request validation, and data classification for every live endpoint. That includes hidden admin paths, debug handlers, versioned endpoints, and any route reachable behind a proxy or gateway. The objective is not simply to make the spec prettier, it is to make the approval boundary match the thing actually deployed.

For APIs, this is also where route drift turns into authorization drift. A path that exists in code but not in the contract may bypass rate limits, monitoring rules, or allowlist logic because the surrounding controls were built from the spec, not from runtime reality. Aligning the two avoids making release decisions on incomplete evidence and reduces the chance of shipping an endpoint whose behavior was never reviewed.

One useful reference point is the OWASP API Security Top 10, because undocumented or drifted routes can turn into authorization and inventory problems long before they become visible incidents.

How teams keep route drift from coming back

Good control here is less about a one-time cleanup and more about making drift hard to reintroduce. The strongest pattern is to generate or validate the specification from the codebase during build and release, then fail the pipeline when declared and discovered routes diverge. That keeps the approval artifact aligned with implementation instead of relying on manual memory.

Teams should also require explicit ownership for every routable endpoint, including temporary, internal, and deprecation-bound paths. Ownership is what makes later decisions possible: whether the endpoint can be exposed, how it will be monitored, when it will be retired, and who can accept residual risk if it stays live. Without that owner, undocumented routes tend to linger.

When the route is tied to secrets or machine-to-machine access, treat the endpoint inventory as part of credential governance as well as API governance. The API Key Management Guide is a useful companion for understanding why undisclosed endpoints can enlarge the blast radius of issued credentials. If a hidden route can be called with an existing key, the problem is not just discovery, it is unintended authority.

The same principle appears in incident evidence such as Dropbox GitHub breach 2022, where exposed source and credential material increased downstream risk once attackers were inside adjacent systems. The lesson for route drift is simple: what is present in code but absent from the spec can still be reachable, and reachable means govern it as real.

Risk and Threat Considerations

Undocumented API routes expand the attack surface because defenders lose reliable inventory, monitoring coverage, and policy enforcement at the same time. That creates a path for accidental exposure, unauthorized use, or later abuse if the route remains reachable after deployment.

Failure mechanism: The route is not included in the expected contract, so review, testing, logging, and authorization controls are applied inconsistently or not at all. Attackers and internal users alike can exploit the gap between what teams believe exists and what the runtime actually serves.

Impact: Sensitive functions may be exposed without proper review, and release decisions may approve a system whose real behavior is not fully understood. Over time, the organization accumulates orphaned endpoints that are difficult to monitor, difficult to retire, and easy to miss during incident response.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

OWASP API Security Top 10 addresses the attack surface, NIST SP 800-53 Rev 5 sets the technical controls, and ISO/IEC 27001:2022 defines the regulatory obligations.

Framework	Control / Reference	Relevance
OWASP API Security Top 10	API9 — Improper Inventory Management	Undocumented routes create API inventory gaps and approval drift.
Recommendation — Inventory all runtime routes and block release until spec and implementation match.
NIST SP 800-53 Rev 5	CM-8 — System Component Inventory	Reachable routes are deployed components that must be inventoried and governed.
	CM-2 — Baseline Configuration	Spec-code parity is part of keeping the approved API baseline under control.
	AC-6 — Least Privilege	Undocumented routes can bypass intended access boundaries and privilege constraints.
Recommendation — Keep an authoritative component inventory that includes live API endpoints. Baseline the approved API contract and fail builds when routes drift. Verify each live route has the minimum necessary access path and authorization.
ISO/IEC 27001:2022	A.5.9 — Inventory of information and other associated assets	API routes are assets that need authoritative inventory and ownership.
Recommendation — Maintain an accurate asset inventory that includes exposed API routes.

Practitioner Guidance

What to verify: Compare runtime discovery against the published spec and make sure every reachable route has method, owner, auth requirements, and deprecation status recorded. If a route cannot be justified in that inventory, treat it as a release blocker rather than an informal exception.

Decision rule: If the route is intended, update the contract before deployment; if it is not intended, remove or disable it before it can be accessed. If you cannot determine intent quickly, escalate it as an ownership and governance defect, not as a minor documentation task.

Practitioner takeaway: The safest boundary is the one your inventory can actually prove. If code and spec disagree, the issue is not wording, it is control of what is really exposed.