Query whitelisting is a way to make the Headless Server more robust against potentially malicious (for example, expensive) queries. When whitelisting is turned on, the Headless Server will execute only the queries loaded into the server during startup (the whitelisted queries). All other queries will be rejected with a HTTP 403 Forbidden response.

Query whitelisting in the Headless Server may be turned on by setting the configuration property caas.persisted-queries.whitelist to true.

Queries issued by clients do not need to match exactly the whitelisted ones. It suffices if their normal form is equal to the normal form of a whitelisted query. The GraphQL controller is configured with a 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.

Query whitelisting 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 whitelisting 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 whitelisting is turned on.