A GraphQL pattern where approved queries are stored in advance and clients can execute only those known requests. This reduces exposure to arbitrary query complexity, limits parser abuse, and makes it easier to enforce depth, cost, and field-level controls across production traffic.
Expanded Definition
Persisted queries are a GraphQL operating pattern in which the server accepts only pre-approved query documents, rather than arbitrary requests assembled by clients at runtime. In practice, this shifts control from “any syntactically valid query” to a known query set that can be reviewed, versioned, and governed before deployment.
The boundary that matters is not simply caching. A cached query can still be user-defined, while a persisted query is intentionally constrained by approval and registry. That distinction is important because the security value comes from reducing the attack surface of query construction, not from speeding up execution alone. In GraphQL environments, this pattern is often paired with allowlisting, complexity limits, and field-level authorization.
Implementation detail matters: if a system still allows ad hoc queries as a fallback, the security benefit is weakened. NHIMG treats that as a common misunderstanding, because teams sometimes describe “persisted” behaviour even when unknown operations are still accepted under certain conditions.
Examples and Use Cases
Persisted queries appear most often where GraphQL is exposed to browsers, mobile apps, or partner integrations that should not be able to craft arbitrary schema requests. They are also useful when teams want consistent production enforcement across a large API surface.
- Mobile clients send a short query identifier, while the server resolves that identifier to a pre-approved GraphQL document.
- API gateways reject unknown operations and route only registered queries into the application layer.
- Teams use persisted queries to support release governance, because each change to query shape can be reviewed before it reaches production traffic.
- Security teams combine persisted queries with depth and cost controls so that approved operations still stay within expected resource bounds.
A practical tradeoff is agility versus control. Persisted queries reduce flexibility for ad hoc client behaviour, but that constraint is often the point: it prevents uncontrolled query variation from becoming a security or reliability problem. The NIST SP 800-53 Rev 5 Security and Privacy Controls is useful background for understanding why controlled execution paths and monitored enforcement matter in production systems.
Security Implications
When persisted queries are misconfigured or treated as optional, GraphQL deployments can drift back toward arbitrary query execution. That reintroduces the kinds of exposure persisted queries are meant to reduce: abusive query nesting, expensive field combinations, parser stress, and inconsistent authorization enforcement across endpoints.
Security issues also appear when the registry is not tightly controlled. If an attacker can register or alter a persisted query, the “approved only” model becomes meaningless. If a client can bypass the registry and submit raw GraphQL, it may be able to probe schema structure, inflate backend load, or reach fields that were never intended for routine access.
The observable symptom is often operational before it is clearly malicious: unusual query shape variance, spikes in resolver work, or repeated requests that do not match the expected application catalogue. For defenders, the important point is that persisted queries are only protective when the allowlist is authoritative and consistently enforced at the edge and application boundary.
Domain and Governance Relevance
Persisted queries sit at the intersection of API governance and application security. They matter because they turn query design into a controlled release artefact rather than a live client capability, which changes who can introduce new request patterns and how those patterns are reviewed.
In identity-heavy environments, the relevance is indirect but real. A stable query catalogue can reduce the chance that every client or service account invents its own access pattern, which makes authorisation easier to reason about and audit. That does not make persisted queries an identity control by themselves, but it does strengthen the surrounding governance model for APIs that expose sensitive business data.
For NHIMG, the practical interpretation is simple: persisted queries are a control boundary for how application access is expressed. They are strongest when treated as part of a broader governance chain that includes schema review, change control, and enforcement of least-privilege field access.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
MITRE ATT&CK address the attack and risk surface, while CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| CIS Controls v8 | 6 — Access Control Management | Persisted queries restrict which operations may execute against the API. |
| 8 — Audit Log Management | Query registry changes and execution of approved operations need auditable records. | |
| Recommendation — Restrict GraphQL execution to approved query IDs and revoke unknown operations. Log query registration, updates, and execution to support review and investigation. | ||
| NIST CSF 2.0 | PR.AC-4 — Access Permissions and Authorizations Managed | Allowlisting queries enforces approved access paths and limits unintended data reach. |
| DE.CM-1 — Assets and Authorised Users Monitored | Unknown or drifting query patterns are a monitoring signal for abuse or misconfiguration. | |
| Recommendation — Enforce approved query allowlists so only authorised request shapes can run. Monitor query registry drift and alert on execution of non-catalogued operations. | ||
| MITRE ATT&CK | T1190 — Exploit Public-Facing Application | Unrestricted GraphQL endpoints can be probed through arbitrary queries and abuse. |
| Recommendation — Map GraphQL abuse paths to T1190 and harden exposed query entry points. | ||
