They can, depending on how you run them. Persisted queries let a client send a short identifier instead of the full query text. If the server accepts only identifiers it already knows, arbitrary queries are rejected, which shrinks the attack surface. If it also accepts new ones on request, the benefit is speed, not security.
Definitions
The GraphQL project describes persisted queries, either as trusted documents or automatic persisted queries, as a way for the client to send a hash of the query while the server looks up the full document in a server side store before validating and executing it. Its stated motivation is performance: shorter requests, and GET requests that fit within URL length limits so HTTP caches and CDNs can help.
Two terms get mixed up:
- Trusted documents (an allowlist model). The set of permitted operations is known ahead of time, usually extracted from your client code at build time. The server runs only those.
- Automatic persisted queries. The client sends a hash. If the server does not know it, the client sends the full text once and the server stores it for next time.
The security difference follows from that. In the first, an attacker cannot run a new query shape. In the second, anyone who can send full text can still register a new query, so you have a cache, not a gate.
What an allowlist helps with
This part is reasoning from how the model works, not a claim from a vendor:
| Problem | Open queries | Trusted documents |
|---|---|---|
| Deeply nested abuse query | Possible, needs limits | Rejected if not in the list |
| Schema probing with guesses | Possible | Unknown operations rejected |
| Expensive query shapes | Possible | Only shapes you reviewed |
| Authorization bugs in listed queries | Still present | Still present |
The last row matters. An allowlist limits which queries can be run. It does not check who is asking for what. Object and field authorization must still be enforced in the business logic layer, as the GraphQL project recommends.
Where it fits and where it does not
Trusted documents suit APIs with first party clients, such as your own web and mobile apps, where you control the queries. They fit poorly for public APIs where outside developers write their own queries. A public API can still use limits, authentication and cost controls instead.
Keep depth, amount and cost limits even with an allowlist. The reviewed queries may still be heavy for some inputs, and an allowlist gets stale if people stop reviewing it.
Steps to adopt
- Inventory the operations your clients really send. Extract them at build time.
- Decide the mode: allowlist only, or hash with fallback. For security, choose allowlist only in production.
- Store the document map server side and version it with your release.
- Reject unknown identifiers and unknown query text in production.
- Keep a development mode that accepts new queries, so engineers are not blocked.
- Test the rejection path. Send a new query to production like settings and confirm it fails.
- Keep your other limits, and keep authorization checks inside resolvers or the business layer.
Trade offs
Allowlists add a build step and a deployment coupling: a new client version needs its documents published before it ships. Rollbacks must include the matching documents. Teams that already ship clients and server together find this easy. Teams with long lived mobile versions need to keep old documents around, which means the allowlist grows and old queries linger.
Try it yourself
Click through it at your own pace, or open it full screen.
Look at the kinds of API issues a scan flags, then decide which an allowlist would reduce.
Quick check
Are automatic persisted queries a security control?
Not by themselves. They mainly reduce request size and help caching. A server that registers new queries on request still accepts arbitrary text.
Do trusted documents replace authorization?
No. They restrict which operations can run, not who may see which data. Keep object and field authorization in place.
Safeguard scans your dependencies and SBOMs for known vulnerabilities, including GraphQL server libraries, and shows which are reachable. A free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
