Registering queries in an allow list is a way to make the Headless Server more robust against potentially malicious (for example, expensive) queries. When allow-list is turned on, the Headless Server will execute only the queries loaded into the allow list of the server during startup. All other queries will be rejected with an error message in the JSON response.

The allow list in the Headless Server may be turned on by setting the configuration property caas.persisted-queries.allow-list to true.

Queries issued by clients do not need to match exactly those in the allow list. It suffices if their normal form is equal to the normal form of an allowed query. This is realized by means of the QueryNormalizer which transforms a GraphQL query string into a normal form, where definitions and fields follow a specific order (for example, lexicographically) and whitespace is minimized.

The allow list is recommended for projects which expose a GraphQL service for some dedicated clients for which the set of queries issued by the clients is known in advance. Usually, you will want to turn allow-list off for your development environment so that front end developers can utilize the full flexibility of GraphQL. Once client development has finished, the queries can be extracted from the client code and transferred to the production environment where allow-list is turned on.