What is a GraphQL operation allowlist, and what abuse does registering documents close?

## The default posture, and why it is unusual A GraphQL endpoint publishes a schema and then accepts documents written against it. That is the point of the style: one URL, and the caller decides the shape of the answer. It also means the endpoint is, by default, a small query language exposed to whoever can reach it. Every other control discussed on a GraphQL security review — depth caps, cost budgets, per-field authorization — exists because the caller writes the document. An **operation allowlist** removes that premise. The server keeps a set of executable documents that were registered ahead of time, and it will run nothing else. A request no longer carries a query; it carries an identifier for one of the registered documents, plus the usual `variables`. On a hit, the server executes **its own stored copy** of the document — never the text the client sent, if it sent any. On a miss, the request is refused. This is a convention, not a specified feature. The GraphQL specification describes how a document is parsed, validated and executed; it says nothing about registering documents in advance. The GraphQL over HTTP work describes how an operation travels over HTTP, and the parameter used to carry a document identifier is not uniform across implementations — some put a top-level identifier field in the JSON body, some carry it under `extensions`. When you discuss this in an interview, say plainly that it is a widespread convention with several spellings rather than attributing it to the specification. ## What it actually closes Think about a hospital appointment graph: clinics, appointments, patients, clinicians, notes. The published schema has cycles in it — an appointment has a clinic, a clinic has appointments — so a caller can legally write a document nineteen levels deep, or repeat the same expensive field forty times under different response keys, or walk the schema through introspection to find a field that was added last week and not yet reviewed. All of those depend on the attacker writing the document. With an enforced allowlist, none of them arrive, because none of them are in the set. The pinned mobile build ships with roughly forty documents; the back-office web app ships with maybe two hundred; nothing else exists as far as the endpoint is concerned. The reduction is not incremental — it converts an open query language into a fixed, enumerable API surface, one whose entire attack surface you can print out and review. That is also the honest limit of the claim. The allowlist bounds **who authors the document**. It does not bound the values that flow into a registered document, it does not decide who may run one, and it does not make a registered document cheap. A document that was expensive on the day it was registered stays expensive and stays allowed. ## The lookup, and why the client's text is not trusted The mechanic worth being precise about: the identifier is a key into the server's store, and the value in that store is the document that executes. If a client sends both an identifier and a document text, an enforced allowlist ignores the text, or refuses the request outright. Any design where the client's text is what runs on a hit has given the client authorship back, which is the thing the control existed to take away. Because the identifier is normally a hash of the text, the identifier and the document cannot drift apart silently: the same text always yields the same key, and a changed document is a different key that is simply not registered yet. That property is what makes the store safe to populate from a release pipeline rather than by hand. ## What it costs you Three things break the day enforcement goes on, and a candidate who has run one will name them without prompting. First, **ad-hoc exploration stops**. A hand-written request, a browser explorer, a debugging one-liner — each is by definition an unregistered document. Teams keep arbitrary documents enabled in non-production, and behind an operator credential in production, precisely so that an incident is survivable. Second, **the release train becomes a dependency**. A client can only send documents that were registered before it shipped, so the registration step has to land ahead of the client release, and it has to keep working for as long as that client is in the field. Third, **the allowlist is fail-closed by design**. That is the property you wanted; it is also the property that turns a registration mistake into an outage rather than a warning. It is why the standard rollout is a log-only period first, with enforcement switched on only once the miss log is empty of legitimate callers. ## How to answer it Say what it is in one sentence — only pre-registered documents run, referenced by identifier — then draw the boundary yourself: it removes attacker-authored documents, and it removes nothing else. Naming a convention as a convention, and naming the limit before the interviewer probes for it, is what separates a memorised definition from an operated control.