Skip to main content
Platform security guideReviewed

GraphQL introspection and security: decide what the schema reveals, then check what each resolver allows

Introspection lets a caller ask a GraphQL API for its own schema.

Whether yours should answer is a decision about who your clients are, not a finding on its own. This guide sets out what the GraphQL specification and the project's own pages say about introspection, how Apollo Server, GraphQL Yoga and GraphQL.js document switching it off, and a workbook for testing object access, field suggestions, aliases, batching, depth, cost and errors on your own schema.

GraphQL schema and resolver review workbook

Part A records the introspection decision for one environment. Part B is ten test rows for your own schema, each with where to look, the requests to send, the result to expect when the control is in place and the source for that expectation.

How to use it

Part C works every row through an invented two-tenant schema on paper; it was not executed, and every response in it is an expected result.

graphql.txt

GRAPHQL SCHEMA AND RESOLVER REVIEW WORKBOOK

Use this on an API you own, in an environment you control, with test accounts you created in two test tenants. Every row reads your own configuration or sends individual requests to your own API, one at a time. Only B2 attempts a write, and only to a test record. Limit rows send one request just over the configured limit and nothing more. Record where a secret lives, never its value, and remove tokens, cookies and personal details from anything you keep.

API name: ______________   Environment checked: ______________   Date: ______________
Server and version, from the lockfile or image: ______________
GraphQL endpoint address: ______________
Other addresses that answer GraphQL for the same data (older versions, staging, services behind a gateway): ______________
Test tenant 1, its users and their roles: ______________
Test tenant 2, its users and their roles: ______________
If your server accepts trusted documents only, how rows B1 to B9 will run (an environment or rule that admits ad hoc documents from test accounts, or approved documents sent with test variables): ______________

==== PART A. INTROSPECTION EXPOSURE DECISION ====

A1. Who calls this API in this environment?
  Choose: only our own web and mobile front ends / partners with their own credentials / anyone (a public API).
  Your answer: ______________
  Basis: graphql.org's Security page says GraphQL APIs that only serve first-party clients may forbid introspection queries in non-development environments. The OWASP GraphQL Cheat Sheet says enabled introspection might be an intended configuration for an API designed to be consumed by external clients.

A2. Is the schema already published somewhere else?
  Choose: public documentation / partner portal / client SDK / not published.
  Your answer and where: ______________

A3. What depends on live introspection in this environment?
  Examples: code generation, an explorer the team uses, a gateway or monitoring tool. Write "nothing" if nothing does.
  Your answer: ______________
  Basis: the GraphQL.js Going to Production guide says many developer tools rely on introspection to function properly.

A4. What the running server answers.
  Send with no session, then as each role, two separate requests:
    { __schema { queryType { name } } }
    { __type(name: "Query") { name } }
  Expected if introspection is off for that caller: refused. A server that refuses it in validation returns a request error, with an errors list and no data entry (GraphQL specification, September 2026 Edition, sections 6.1.1 and 7.1.3). Expected if on: data holding the query type's name.
  Why both: the specification makes __schema and __type both available from the root query type (section 4.2).
  Record for each caller and request: HTTP status, whether data is present, and the error message word for word: ______________

A5. Where the setting lives and its value.
  Apollo Server: the introspection option if one is passed. If not, the NODE_ENV environment variable or the nodeEnv option, because the documented default is true unless NODE_ENV is set to production (Apollo Server API reference).
  GraphQL Yoga: whether useDisableIntrospection is installed, and what its isDisabled function reads (Yoga Introspection page).
  GraphQL.js: whether NoSchemaIntrospectionCustomRule is in the validation rules, and for which requests (GraphQL.js Going to Production guide).
  Another server: the setting its own documentation names, and that documentation page: ______________
  Your setting, the file it is in, and its value in this environment: ______________

A6. Decision.
  Choose: on for every caller / on only for named roles or requests / off for every caller.
  Reason, from A1 to A3: ______________
  Does any access rule depend on the schema staying hidden? Part B tests the rules directly, so the answer should be no. Your answer: ______________
  Decided by, and date: ______________

==== PART B. TEST ROWS FOR YOUR SCHEMA ====
Each row says where to look, what to send, what to expect when the control is in place and why, and what to record. Write your own expected result before you send anything.

B1. Every path to a tenant record: object-level authorisation on reads
  Where to look: the schema. For each type that holds tenant data, list every field that returns it: top-level fields that take an ID, any node or nodes field, fields and connections on other types, search fields, and mutation payloads.
  Send: signed in as a tenant 1 user, ask for one tenant 2 record through every read path on the list (mutation payloads are covered in B2). Then ask for an ID that does not exist through the same paths.
  Expected: every path answers the tenant 2 ID exactly as it answers the missing ID, and no field of the tenant 2 record appears in data or in errors.
  Basis: OWASP API1:2023 asks for an authorisation check in every function that uses input from the client to access a database record. The OWASP GraphQL Cheat Sheet asks for checks on both edges and nodes, and says node or nodes fields can reach objects by ID even where that was not intended. The matching answer is this page's advice.
  Record: type, path, request, response, pass or fail: ______________

B2. Object-level authorisation on mutations
  Where to look: every mutation that takes an ID or returns tenant data.
  Send: on your own API, signed in as a test user in test tenant 1, each mutation with the ID of a test record you created in test tenant 2. The request writes only if the control is missing, and then only to that test record. Where even that is not acceptable, read the mutation's code path to its access check instead and record what you read.
  Expected: refused, or answered as for a missing ID; no tenant 2 data in the payload; and the record unchanged when its owner reads it back.
  Basis: graphql.org's Authorization page says that for a production codebase, authorisation logic should be delegated to the business logic layer, as a single source of truth for every entry point. The refused or missing-ID answer and the read-back are this page's advice.
  Record: mutation, record, response, and the record as its owner reads it afterwards: ______________

B3. Field-level rules
  Where to look: fields one role should not read, such as internal notes or cost prices.
  Send: as the lower role, one query per path from B1 that selects the restricted field.
  Expected: the field withheld on every path, while the higher role still receives it.
  Basis: OWASP API3:2023 covers object properties a caller should not read, and notes that for protocols such as GraphQL it may require crafted requests to specify which properties should be returned. The OWASP GraphQL Cheat Sheet's Query Access section describes a check that the requester may read each field.
  Record: field, role, path, result: ______________

B4. Field suggestions
  Where to look: GraphQL.js hideSuggestions (in v17, in v16 from v16.15.0 and in v15 from v15.11.0; suggestions are on by default). Apollo Server hideSchemaDetailsFromClientErrors (default false). GraphQL Yoga: the GraphQL Armor blockFieldSuggestionsPlugin.
  Your setting and value: ______________
  Send: with no session, one query that selects a field one letter away from a real field name.
  Expected if suggestions are hidden: the error names the unknown field and its type, and suggests nothing.
  Basis: Apollo Server's API reference prints the message both ways. graphql.org's Security page says that even with introspection disabled, an attacker could ultimately infer the shape of an entire schema by running numerous operations with incorrect field names.
  Record: the message word for word: ______________

B5. Aliases
  Where to look: the alias or breadth limit in your server or plugin configuration, and how it counts.
  Configured limit: ______________
  Send: one read-only query with one more alias than the limit, every alias on a field your test user may read.
  Expected: rejected before execution, with an errors list and no data entry.
  Basis: graphql.org's Security page recommends guardrails on the number of top-level fields and field aliases in a single operation. A request error carries no data entry (specification section 7.1.3). Rejection before execution is this page's expectation for a limit applied while the document is validated; record when yours applies it.
  From configuration only, send nothing: do attempt limits on sign-in or code-check mutations count each aliased field? The specification executes the top-level fields of a mutation serially, one after another (sections 6.2.2 and 6.3.4). Your answer: ______________
  Record: limit, request, response: ______________

B6. Batching
  Where to look: Apollo Server allowBatchedHttpRequests (default false). GraphQL Yoga batching (disabled by default; when enabled, up to 10 requests in one HTTP request by default, or the limit you set).
  Configured state and limit: ______________
  Send: one HTTP POST whose body is a JSON array holding one more request object than the limit, or two objects if batching should be off.
  Expected: refused as a whole. Apollo Server's API reference names the error Operation batching disabled. Yoga's Batching page gives HTTP status 413 and, for a limit of 2, the message Batching is limited to 2 operations per request. That none of the operations runs is this page's expectation; check it in your server logs.
  Record: status, message, and whether any operation ran: ______________

B7. Depth
  Where to look: the depth rule or plugin, its limit, and how its documentation counts depth.
  Configured limit and counting rule: ______________
  Depth of the deepest operation your own front end sends: ______________
  Send: one query one level deeper than the limit, following a loop in your data.
  Expected: an error, returned before execution begins.
  Basis: graphql.org's Security page says many implementations let you set a maximum depth and return an error if a request exceeds it before execution begins.
  Record: request, response: ______________

B8. Cost and page size
  Where to look: any cost or complexity rule, its weights and its maximum, and the maximum for each list argument such as first.
  Configured maximum score and page size: ______________
  Send: one query just over the maximum score, using nested lists that each stay within the page size. Then one list argument above the page size.
  Expected: the first rejected before execution. The second refused, or capped at the maximum, whichever your API documents.
  Basis: graphql.org's Security page says a request over the maximum allowable cost may be rejected outright, and that a list field that could return a lot of data should be paginated. Rejecting the first before execution is this page's expectation. OWASP API4:2023 lists the number of records per page among the limits that make an API vulnerable when missing or set inappropriately.
  Record: your estimate, the response, and the number of items returned: ______________

B9. Errors
  Where to look: Apollo Server includeStacktraceInErrorResponses (defaults to true unless NODE_ENV is production or test) and formatError. GraphQL Yoga maskedErrors and NODE_ENV. GraphQL.js: your error formatter.
  NODE_ENV in the running environment: ______________
  Send: a document with its closing brace missing. Then a valid query with an argument value your resolver rejects.
  Expected: the first returns an errors list with a message and no data entry. The second returns null at the field (or, if the field is Non-Null, at the nearest position above it that can be null), an error with a path, and nothing in the message or extensions that names a file, stack frame, database query, host or library version.
  Basis: specification sections 6.4.4, 7.1.3 and 7.1.6. graphql.org's Security page says details of errors raised during field execution should be masked. Naming nothing internal is this page's advice.
  Record: both responses, with anything internal marked: ______________

B10. Persisted or trusted documents
  Where to look: whether an allowlist is enforced, where its store lives, and whether a request can add to it. Apollo Server: persistedQueries (its APQ page says Apollo Server supports APQ without any additional configuration). GraphQL Yoga: usePersistedOperations, and whether allowArbitraryOperations is set and what it reads.
  Send, as a test account and without any rule that admits ad hoc documents:
    (a) the hash of an approved document, with your own test variables;
    (b) an unapproved document, sent as query;
    (c) an unapproved document together with its own SHA-256 hash, in the APQ format;
    (d) then that hash alone.
  Expected with an allowlist: (a) runs; (b), (c) and (d) are refused.
  Basis: the GraphQL.js Going to Production guide says the server should reject the request if no document is found or no hash is provided. Yoga's Persisted Operations page shows an operation outside the store refused with the message PersistedQueryOnly. Apollo's APQ page describes a server that stores a query string sent with its hash and then answers the hash alone, which is the behaviour (c) and (d) look for.
  Also: send (a) with another tenant's ID in the variables. An approved document still has to pass B1.
  Record: each response: ______________

==== PART C. WORKED EXAMPLE ON PAPER ====
An illustration. The schema, tenants, accounts, records, limits and requests below were written for this page. None of it was run against a server. Each response shown is the response the test should produce when the control is in place, with its basis. The two SHA-256 hashes were computed for this page from the exact document strings printed in C12, character for character. The same calculation gives ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38 for {__typename}, the hash printed in Apollo Server's APQ page and Yoga's Persisted Operations page.

C1. The invented API
  Host: gql.jobs.lab.test, an invented host name. Tenant A and tenant B are two invented trades businesses that share one job and invoice app.
  Users: a-owner (OWNER) and a-staff (STAFF) in tenant A; b-owner (OWNER) and b-staff (STAFF) in tenant B.
  Records: invoice inv_A1 and customer cus_A7 in tenant A; invoice inv_B1 and customer cus_B3 in tenant B. Each customer owns its tenant's invoice. inv_ZZ9 does not exist.
  Rules: every user sees only their own tenant. Only OWNER reads internalNote.
  Server: GraphQL Yoga with useDisableIntrospection, the GraphQL Armor block field suggestions, Max Aliases, Max Depth and Cost Limit plugins, batching with a limit of 3, and usePersistedOperations. Every limit below is this example's choice, not a plugin default.
  Limits: 10 aliases per operation. Depth 10, counting each field as one level from 1 at the root field. A maximum score of 1,000, where each Invoice or Customer returned scores 1 and a list scores its first argument times the score of one element; real plugins document their own scoring. Page size at most 50.
  Documents: ordinary callers may send approved documents only. On staging, Yoga's allowArbitraryOperations admits ad hoc documents from requests carrying the invented test-only header x-review-ops, so rows B1 to B9 run there with that header. Yoga's documentation says to use that option with caution, and B10 runs without the header.

C2. The schema

type Query {
  viewer: User!
  invoice(id: ID!): Invoice
  invoices(first: Int = 20, after: String): InvoiceConnection!
  customer(id: ID!): Customer
  node(id: ID!): Node
}

type Mutation {
  addInvoiceNote(id: ID!, text: String!): Invoice
  verifyLoginCode(email: String!, code: String!): LoginResult!
}

interface Node {
  id: ID!
}

enum Role {
  OWNER
  STAFF
}

type User implements Node {
  id: ID!
  name: String!
  role: Role!
  tenant: Tenant!
}

type Tenant implements Node {
  id: ID!
  name: String!
  customers(first: Int = 20, after: String): CustomerConnection!
}

type Customer implements Node {
  id: ID!
  name: String!
  email: String!
  tenant: Tenant!
  invoices(first: Int = 20, after: String): InvoiceConnection!
}

type Invoice implements Node {
  id: ID!
  number: String!
  totalCents: Int!
  internalNote: String
  customer: Customer!
}

type CustomerConnection {
  edges: [CustomerEdge!]!
  pageInfo: PageInfo!
}

type CustomerEdge {
  node: Customer!
  cursor: String!
}

type InvoiceConnection {
  edges: [InvoiceEdge!]!
  pageInfo: PageInfo!
}

type InvoiceEdge {
  node: Invoice!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

type LoginResult {
  ok: Boolean!
  token: String
}

C3. Part A, filled in
  A1: only our own web app. A2: not published; the schema file lives in the repository. A3: code generation reads the schema file at build time, so nothing in production needs live introspection.
  A4 expected for every caller, for both requests: refused. Yoga's Introspection page does not say at which stage the plugin refuses; if it refuses in validation, the response is a request error with an errors list and no data entry, as in A4. Record what it returns.
  A5: useDisableIntrospection installed without an isDisabled function, as in the first example on Yoga's Introspection page.
  A6: off for every caller. No access rule depends on the schema staying hidden.

C4. B1, every path to inv_B1, sent as a-staff
  Paths that return an Invoice, read from the schema: Query.invoice, Query.node, Query.invoices, Customer.invoices, and the payload of Mutation.addInvoiceNote (row C5). A Customer is itself reached through Query.customer, Query.node, Tenant.customers and Invoice.customer, so the census lists those for Customer too; the queries below show one route each.

  query PathOne { invoice(id: "inv_B1") { number totalCents } }
  Expected: {"data":{"invoice":null}}, the same response as for invoice(id: "inv_ZZ9").

  query PathTwo { node(id: "Invoice:inv_B1") { ... on Invoice { number } } }
  Expected: {"data":{"node":null}}.

  query PathThree { customer(id: "cus_B3") { invoices(first: 5) { edges { node { number } } } } }
  Expected: {"data":{"customer":null}}.

  query PathFour { invoices(first: 50) { edges { node { id } } } }
  Expected: tenant A invoice IDs only, so inv_A1 and never inv_B1.

  Basis: OWASP API1:2023 and the OWASP GraphQL Cheat Sheet, as in B1. Answering null, the same as for a missing ID, is this example's design and this page's advice.

C5. B2 and B3
  mutation NoteOnOther { addInvoiceNote(id: "inv_B1", text: "review test") { number } }   sent as a-staff, on test records
  Expected: {"data":{"addInvoiceNote":null}}, the same response as for inv_ZZ9, and inv_B1 has no new note when b-owner reads it back.

  query StaffNote { invoice(id: "inv_A1") { number internalNote } }   sent as a-staff, then as a-owner
  Expected for a-staff: internalNote is null. If the server says why, the error's path is ["invoice", "internalNote"] (section 7.1.6), and the specification handles that position as though it resolved to null (section 6.4.4). Expected for a-owner: the note. The rule itself is this example's.

C6. B4, field suggestions, sent with no session
  query Typo { invoice(id: "inv_A1") { internalNot } }
  Expected with suggestions hidden: an errors list, no data entry (specification sections 6.1.1 and 7.1.3), and a message that names the unknown field and its type and suggests nothing. Written in the format Apollo Server's API reference prints with hideSchemaDetailsFromClientErrors set to true, that message is
    Cannot query field "internalNot" on type "Invoice".
  This page does not show the GraphQL Armor plugin's own wording; record the message your server returns. With suggestions on, the format Apollo shows would add a hint naming the real field, internalNote.

  query TypoTwo { node(id: "Invoice:inv_A1") { number } }
  Here the parent type, Node, is an interface. The GraphQL.js 16.x rule for unknown fields first looks for types to use an inline fragment on, so with suggestions on, its hint would name the type Invoice. With hideSuggestions set, it names nothing.

C7. B5, aliases, limit 10
  query ElevenAliases {
    n1: invoice(id: "inv_A1") { number }
    n2: invoice(id: "inv_A1") { number }
    n3: invoice(id: "inv_A1") { number }
    n4: invoice(id: "inv_A1") { number }
    n5: invoice(id: "inv_A1") { number }
    n6: invoice(id: "inv_A1") { number }
    n7: invoice(id: "inv_A1") { number }
    n8: invoice(id: "inv_A1") { number }
    n9: invoice(id: "inv_A1") { number }
    n10: invoice(id: "inv_A1") { number }
    n11: invoice(id: "inv_A1") { number }
  }
  Sent as a-owner. Expected: rejected before execution, an errors list, no data entry. Record the plugin's message as received.
  From configuration only: the verifyLoginCode attempt counter counts each aliased field, not each HTTP request. No code-check request is sent.

C8. B6, batching, limit 3
  One POST to /graphql with Content-Type: application/json and this body:
  [{"query":"{ viewer { name } }"},{"query":"{ viewer { name } }"},{"query":"{ viewer { name } }"},{"query":"{ viewer { name } }"}]
  Expected: HTTP status 413 and an errors list, as on Yoga's Batching page. That page gives the message for a limit of 2 as Batching is limited to 2 operations per request.; record the wording you receive for yours. That none of the four operations runs is this page's expectation. On Apollo Server with allowBatchedHttpRequests left false, even two objects are refused, with the error its API reference names Operation batching disabled.

C9. B7, depth, limit 10
  The deepest approved document, the invoice list, is 5 levels: invoices, edges, node, customer, name.
  query TooDeep {
    invoice(id: "inv_A1") {
      customer {
        invoices(first: 2) {
          edges {
            node {
              customer {
                invoices(first: 2) {
                  edges {
                    node {
                      customer {
                        name
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  That is 11 levels under this example's counting rule: invoice 1, customer 2, invoices 3, edges 4, node 5, customer 6, invoices 7, edges 8, node 9, customer 10, name 11.
  Expected: rejected before execution, an errors list, no data entry. A request error result has an errors list and no data entry (specification section 7.1.3).

C10. B8, score and page size
  query TooCostly {
    invoices(first: 20) {
      edges {
        node {
          customer {
            invoices(first: 50) {
              edges {
                node {
                  number
                }
              }
            }
          }
        }
      }
    }
  }
  Score under this example's weights: 20 outer invoices, each with 1 customer and 50 inner invoices, so 20 times 52, which is 1,040 against a maximum of 1,000. Depth is 8, under the limit, so only the score rule stops it.
  Expected: rejected before execution, an errors list, no data entry. A request error result has an errors list and no data entry (specification section 7.1.3).

  query TooMany { invoices(first: 51) { edges { node { id } } } }
  Expected: this example refuses it with a request error. An API that documents capping instead would return at most 50 items.

C11. B9, errors
  query Broken { invoice(id: "inv_A1") { number }
  (the closing brace is missing on purpose)
  Expected: an errors list whose error has a message and locations, and no data entry (sections 7.1.3 and 7.1.6).

  query BadId { invoice(id: "not-an-id") { number } }
  In this example the invoice resolver passes the ID to a database lookup that throws on a malformed ID.
  Expected with Yoga's default masking, and NODE_ENV not set to development: data.invoice is null; the error's message is Unexpected error. and its path is ["invoice"]; and extensions carries no originalError and no stack trace. Basis: Yoga's Error Masking page, and specification sections 6.4.4 and 7.1.6 (invoice can be null in this schema).

C12. B10, trusted documents, sent without the x-review-ops header
  Approved document, exactly as stored:
  query InvoiceSummary($id: ID!) { invoice(id: $id) { id number totalCents customer { name } } }
  SHA-256: 2bd2720752390567250ac8bcdfb0329d24d9e2e8228fba9b2b307dc5789a45b6

  (a) As a-owner, in the APQ format Yoga's plugin follows by default:
  {"extensions":{"persistedQuery":{"version":1,"sha256Hash":"2bd2720752390567250ac8bcdfb0329d24d9e2e8228fba9b2b307dc5789a45b6"}},"variables":{"id":"inv_A1"}}
  Expected: data.invoice holds inv_A1's id, number, total and customer name.
  The GraphQL.js guide's form of the same request, for servers built that way:
  {"documentId":"sha256:2bd2720752390567250ac8bcdfb0329d24d9e2e8228fba9b2b307dc5789a45b6","variables":{"id":"inv_A1"}}

  (a) again, as a-staff with "variables":{"id":"inv_B1"}
  Expected: {"data":{"invoice":null}}. The allowlist approved the document, not the record.

  (b) An unapproved document, sent as query:
  {"query":"query InvoiceSummary($id: ID!) { invoice(id: $id) { id number totalCents customer { name } internalNote } }","variables":{"id":"inv_A1"}}
  Expected: {"errors":[{"message":"PersistedQueryOnly"}]}, as in Yoga's Persisted Operations example.

  (c) The same unapproved document with its own hash added:
  "extensions":{"persistedQuery":{"version":1,"sha256Hash":"bfe625c4561211b85b8035cbaf9f9833b97c9c6d5d22302a70d407e0c037059b"}}
  Expected: refused, and nothing added to the store. Yoga's Persisted Operations page does not show this request; the expectation is this page's, for a store that only deployment writes to.

  (d) That hash alone, in the format of (a).
  Expected: refused, because no approved document has that hash, which is when the GraphQL.js guide says the request should be rejected. If (c) returns data, the server ran a document outside the allowlist. If (d) then returns data too, it also stored that document, the way Apollo's APQ page describes.

  From configuration: the x-review-ops rule exists in the staging build only.

C13. What the example cannot show
  It was not executed. The messages a real server and its plugins return differ from the ones above, and depth and score are counted the way each tool's documentation says. Record what your own server returns, and keep the request beside it.

What GraphQL introspection is, in the specification's terms

graphql.org's guide to serving GraphQL over HTTP says a GraphQL server operates on a single URL or endpoint, usually /graphql, and that all GraphQL requests for a given service should be directed to it.

Each request carries a document naming the fields it wants, or an ID that stands for one, so what a caller can ask for is set by the schema rather than by a list of paths. The API security guide in this library covers APIs in general and the endpoint register. This page covers what changes when every operation lives in one schema behind one address.

Introspection is how a caller reads that schema through the API itself. The September 2026 Edition of the GraphQL specification says a GraphQL service supports introspection over its schema, and that the schema is queried using GraphQL itself.

Section 4.2 makes the meta-fields __schema and __type available from the root query type, and notes that, like all meta-fields, they are implicit and do not appear in the root type's list of fields.

Section 4.1 adds the meta-field __typename, which returns the name of the concrete object type at that point in any selection set, except selections at the root of a subscription.

What comes back is the shape of the API. The __Schema type in the specification has fields for the schema's types, its query, mutation and subscription root types, and its directives. Each type can describe its fields, interfaces, possible types, enum values and input fields, and fields, arguments, input fields and enum values can say whether they are deprecated and why. graphql.org's introspection page says these queries help power GraphQL development tools. The same list is what an outsider would want before writing operations of their own.

What GraphQL enforces for you, and what stays with your code

The specification gives every conforming server some checks.

Only operations from documents that pass all validation rules should be executed, and a request with known validation errors must fail without execution (section 6.1.1). Validation requires every selected field to be defined on its type (section 5.3.1), and forbids fragment spreads that form a cycle, because an operation could otherwise infinitely spread or infinitely execute on cycles in the underlying data (section 5.5.2.2). These checks concern the shape of a request, not who sent it.

The rest is configuration and code. The GraphQL.js Going to Production guide says GraphQL does not include built-in authentication, and that you can attach user data to the request using middleware and pass it through to the business logic, where authorisation should take place. graphql.org's security page says the specification gives no guidelines on query complexity analysis or rate limits.

Introspection, error suggestions, alias, batch, depth and cost limits, and error masking are each set in the server or a plugin, and the sections below give each server's documented default where its documentation states one. The access rules live in your resolvers and the business logic behind them.

GraphQL introspection is an exposure decision, not a finding by itself

Whether introspection answers on your production API depends on who your clients are, and graphql.org and the OWASP GraphQL Cheat Sheet each tie it to that question. graphql.org's security page says GraphQL APIs that only serve first-party clients may forbid introspection queries in non-development environments.

Its introspection page says that for APIs intended only for your own applications, introspection is typically not needed in production, because the operations they need are usually built into them at build time, and that disabling it in production is common in order to reduce the API's attack surface.

The OWASP GraphQL Cheat Sheet addresses it in its access control steps and again in its introspection section. Among the access control steps, it lists disabling introspection queries system-wide in any production or publicly accessible environment. The introspection section then says leaving it enabled might be an intended configuration for an API designed to be consumed by external clients, that for a publicly consumed API you might consider disabling it for callers who are not authenticated or not authorised, and that for an internal API the easiest approach is to disable it system-wide.

graphql.org also says what switching it off does not do. Its security page says disabling introspection can be used as a form of "security through obscurity", but will not be sufficient to obscure a GraphQL API entirely by itself, and that trusted documents and authorisation should be used for more comprehensive protection of schema details and user data.

Its recap calls a document allowlist likely to be a more effective solution. The GraphQL.js guide marks its introspection step as unnecessary if you only allow trusted documents, and notes that many developer tools rely on introspection to work.

This page therefore gives no verdict on your introspection setting. Part A of the workbook opens with three questions: who calls the API, whether the schema is already published somewhere else, and what in each environment depends on live introspection.

It then records what the running server answers, where the setting lives and the decision itself. A public API with published documentation and an internal API behind one front end can reasonably land in different places.

In this page's view, what matters is that production runs the setting you decided on, and that no access rule depends on the schema staying hidden.

How Apollo Server, GraphQL Yoga and GraphQL.js document the switch

Each server documents introspection in its own terms.

The default matters as much as the option name, because a default that depends on an environment variable can differ between the server you checked and the one serving customers.

  • Apollo Server. The API reference for the @apollo/server package, in its v4 to v5 documentation, describes an introspection option that, if true, enables schema introspection by clients. Its default value is true, unless the NODE_ENV environment variable is set to production. A separate nodeEnv option, if set to any string, is used instead of NODE_ENV for the features whose defaults depend on it, introspection among them.
  • GraphQL Yoga. The introspection page in the Yoga documentation, marked v6, switches introspection off with the useDisableIntrospection plugin from @graphql-yoga/plugin-disable-introspection, next to graphiql: false. The plugin's isDisabled option can decide from the request, in its example from a header, or from the context, in its example when no JWT is present. The same page highly recommends persisted operations where the goal is to stop unknown actors reverse-engineering the schema and executing arbitrary operations.
  • GraphQL.js. The reference implementation's Going to Production guide adds NoSchemaIntrospectionCustomRule to the validation rules, in its example for public requests only, so introspection can be refused in production or only for callers who are not signed in.

Confirming the setting from outside

Two checks follow, both this page's advice. Read the setting from the deployed environment rather than from the code alone, since an environment variable can change the answer. Then send one introspection request with no session and one as each role, asking for __schema and, separately, for __type, because the specification provides both entry points.

Keep the response, including the error message if the request is refused, because that message is what an outsider sees too.

Field suggestions: schema hints that outlive introspection

Switching introspection off does not stop a server describing its schema in error messages.

In GraphQL.js, the validation rule for unknown fields on the 16.x line reports an error that begins Cannot query field, with the field and type names, and appends any suggestion it finds unless suggestions are hidden. It first looks for types to use an inline fragment on, which it does only when the parent type is abstract, and if it finds none it suggests similar field names.

Apollo Server's API reference gives an example in the same format, as it reads with hideSchemaDetailsFromClientErrors set to false: Cannot query field "help" on type "Query". Did you mean "hello"?

graphql.org's security page explains why that matters. It says these hints may provide more information about a schema in production than you would like to reveal, and that even with introspection disabled, an attacker could ultimately infer the shape of an entire schema by running numerous operations with incorrect field names.

The GraphQL Yoga documentation says the suggestions can be considered a security issue, because they can leak information about the schema even if introspection is disabled. The OWASP cheat sheet suggests considering switching them off once introspection is off, and adds that not all implementations support doing so.

  • GraphQL.js: the hideSuggestions option, which its production guide says is available in v17, in v16 from v16.15.0 and in v15 from v15.11.0. Suggestions remain enabled by default. Where validate() and execute() are called separately, the guide says to pass the option to both, and it notes that custom scalar and resolver error messages are unaffected.
  • Apollo Server: the hideSchemaDetailsFromClientErrors option, if true, strips "did you mean" suggestions when an operation fails validation. Its default value is false, and Apollo recommends enabling it in production to avoid leaking information about the schema.
  • GraphQL Yoga: the documentation switches suggestions off with the blockFieldSuggestionsPlugin from GraphQL Armor, installed as @escape.tech/graphql-armor-block-field-suggestions.

One request answers it

The workbook row for suggestions is a single invalid query, a field name one letter away from a real one, sent with no session. Whatever the configuration file says, the message that comes back shows whether hints are on in that environment.

Object-level authorisation: every path to a record, not every endpoint

In a REST API, each path is a line in the endpoint register.

In GraphQL, one record can be reached through a top-level field that takes its ID, through a node field that resolves any ID, as a nested field of another object, inside a list or a search, and in the payload a mutation returns.

The OWASP GraphQL Cheat Sheet says to enforce authorisation checks on both edges and nodes, and notes that node or nodes fields can give access to objects by ID even where that was not intended.

OWASP's API1:2023 entry gives the general rule: an authorisation check in every function that uses input from the client to access a database record.

graphql.org places the check in the business logic that resolvers call. Its page on authorisation says that for a production codebase the logic should be delegated to the business logic layer, because a check written into a field resolver has to be duplicated for each entry point, and copies that fall out of sync could let users see different data depending on which API they use.

Its guide to serving over HTTP says GraphQL should sit after authentication middleware, and that field-level authorisation should be enforced by the business logic called from resolvers during execution, which allows a partial response when an authorisation error is raised.

So the test is a census of paths. For each type that holds tenant data, list every field in the schema that returns it, directly or inside a connection, and every mutation whose payload includes it. Then, signed in as a user in one test tenant, ask for a record belonging to the other tenant through every path on the list.

In this page's advice, each path should answer exactly as it would for an ID that does not exist, with none of the record's fields in data or in errors.

The broken access control guide covers the check itself and the choice between a refusal and a not-found answer.

Field-level rules belong in the same census. OWASP's API3:2023 entry says APIs tend to expose endpoints that return all of an object's properties, and that for other protocols such as GraphQL it may require crafted requests to specify which properties should be returned. Selecting fields by name is how every GraphQL query works, so a restricted field is one query away on every path that returns its type.

If a staff role should not read an internal note on an invoice, each of those paths has to withhold it, and the workbook checks them with one query per path.

Aliases and batching: many operations in one request

An alias renames a field in the response.

The specification's example (section 2.8) fetches the profilePic field at sizes 64 and 1024 under the aliases smallPic and bigPic, and says fields at the top level of an operation can be aliased as well. One request can therefore call the same field many times with different arguments. graphql.org's security page recommends guardrails on the number of top-level fields and field aliases in a single operation, and the OWASP cheat sheet's batching example requests several droid objects by ID in one query, using aliases such as second and third.

Batching applies the same idea to whole requests. graphql.org describes a client sending a document with many batched operations and says there should be an upper limit on the total number of queries allowed in a single batch.

The specification itself executes one operation per request: when a document holds several, each must be named and the request must say which to run (sections 2.3 and 6.1). The batching that Apollo Server and GraphQL Yoga document instead takes several request objects in one HTTP body, as an array, and the OWASP cheat sheet's first batching example has the same shape. The documented defaults:

  • Apollo Server: allowBatchedHttpRequests defaults to false. A request formatted as an array rather than a single request object gets an error, which the API reference names Operation batching disabled, unless batching is enabled.
  • GraphQL Yoga: batching is disabled by default and is switched on with the batching option. Once it is on, up to 10 GraphQL requests are allowed in one HTTP request by default. The documentation says exceeding the limit returns HTTP status 413, and its example error, for a limit of 2, reads Batching is limited to 2 operations per request.

Why one request can get past a request counter

In OWASP's API4:2023 entry, an API is vulnerable when any one of its listed limits is missing or set inappropriately, and the list includes the number of operations to perform in a single API client request, for example GraphQL batching. Its second attack scenario is a GraphQL endpoint whose traditional rate limit is bypassed by many upload operations sent in one batched request.

The OWASP GraphQL Cheat Sheet adds that the issues batching attacks can lead to include enumeration of objects and brute forcing of passwords, one-time codes or session tokens, and that this attack will likely bypass existing rate limits in proxies or gateways that look at the raw number of requests. The rate limiting guide covers how to count work rather than requests.

Aliased mutations run one after another

The specification says the top-level fields of a mutation are executed serially, starting with the first field in the document. An operation that aliases a code-checking mutation ten times therefore asks the server to run ten checks in turn, inside one HTTP request. The cheat sheet's mitigations include object request rate limiting in code and preventing batching for sensitive objects.

This page's advice follows from both: count each aliased field against an attempt limit, not each HTTP request. The workbook reads that setting from configuration and sends no attempts at a sign-in flow.

GraphQL query depth limiting, cost and page sizes

Depth comes from relationships.

If an invoice has a customer and a customer has invoices, a query can follow that loop as far as the client writes it. The specification forbids cycles between fragment spreads, but graphql.org's security page shows a query that nests fields along a loop directly, hero then friends inside friends, and says some queries may become cyclical when fields are deeply nested.

It says limiting the maximum depth of fields in a single operation is a good idea, that many implementations let you set a maximum and return an error before execution begins, and that a separate, smaller limit on how deeply lists can be nested is recommended, because nesting list fields can increase the data returned exponentially.

  • GraphQL.js: the Going to Production guide's example adds depthLimit(10) from the graphql-depth-limit package to the validation rules, and says that instead of depth you can assign each field a cost and reject queries that exceed a total budget.
  • Apollo Server: the API reference documents maxRecursiveSelections, false by default. Set to true, it errors when the operation would hold more than 10,000,000 selections with its named fragments recursively inlined; set to a number, it uses that number instead. It counts selections, which is a different measure from depth.
  • GraphQL Yoga: its Preparing for Production page recommends, for public APIs, the GraphQL Armor plugins Cost Limit, Max Tokens, Max Aliases, Max Depth and Max Directives, and says that, depending on the type and complexity of the operations executed, their configuration may need adjusting.

Cost catches what depth misses

A shallow query can still ask for fifty customers with fifty invoices each. graphql.org describes query complexity analysis: weights on types and fields give an estimated cost per request, a request over the maximum can be rejected outright, and the estimate can be deducted from a client's budget for a period.

The OWASP cheat sheet says cost analysis is not easy to implement and may not always be necessary, and calls it the most thorough approach to preventing denial of service.

Page sizes

graphql.org says a list field that could return a lot of data should be paginated, to limit the items returned in a single request. The OWASP cheat sheet's amount example is posts(first: 99999999), and it says depth and amount can both be unlimited by default. The workbook records the configured maximum for each list argument and sends one request just above it.

None of these limits needs volume to check. A limit either rejects the one request that exceeds it or it does not. Load and denial-of-service testing is separate work, and nothing on this page describes it.

Error responses: what the errors list carries

The specification fixes the outline of a GraphQL error and leaves its content to the server.

Every error must carry a message, written as a guide for the developer. It should carry locations when it points at a place in the document, and must carry a path when it belongs to a field in the result. Services may add an extensions entry, reserved for implementers, with no restrictions on its contents.

A request error, raised before execution, returns errors and no data entry at all. An execution error, raised while one field runs, gives partial data: the failed position holds null or is missing, and the error goes in the errors list.

graphql.org's security page says details of errors raised during field execution should be masked, because they may reveal sensitive information about the server or underlying data sources. What each server documents:

  • Apollo Server: includeStacktraceInErrorResponses, if true, includes stack traces in responses when errors occur, and defaults to true unless NODE_ENV is production or test. The formatError option transforms errors before they are sent to a client.
  • GraphQL Yoga: unexpected errors are masked without any configuration, and the documentation's example returns the message Unexpected error. With NODE_ENV set to development, Yoga adds the original error and its stack trace under extensions, which maskedErrors with isDev set to false prevents. Errors thrown as a GraphQLError keep their own message.
  • GraphQL.js: the Going to Production guide says that by default it includes full error messages and stack traces, and shows a custom error formatter returning a generic error in production.

Two requests that show the defaults

The workbook sends a document that does not parse, which should come back as a request error with no data entry, and an argument your resolver rejects, which should come back as an error with a path and null at the field, or at the nearest position above it that can be null when the field is Non-Null (specification section 6.4.4).

Read the message and the extensions of the second for file names, stack frames, database queries, hosts and library versions. The sensitive data exposure guide covers error messages across the rest of an application.

Persisted documents, trusted documents and automatic persisted queries

For an API that serves only your own front ends, graphql.org and the GraphQL.js guide describe trusted documents. graphql.org says that, as a build step, clients may submit their documents to the server's allowlist, each stored with a unique ID, usually its hash.

At runtime the client can send the ID instead of the document, and the server will only execute requests for known IDs. The same page calls trusted documents persisted documents deemed not to be malicious, usually because your developers wrote them and approved them through code review, and says they cannot be used for public APIs, because third-party operations are not known in advance.

The GraphQL.js guide calls the pattern the most reliable way to protect a GraphQL endpoint from malicious requests, with the same exception for public APIs.

The GraphQL.js guide describes the mechanics. Each document is hashed with SHA-256 at deployment and placed in a trusted store. The client sends the hash, written as "documentId": "sha256:..." in its example, instead of the document.

The server retrieves the document from the store by that hash, and if no document is found or no hash is provided, the guide says the request should be rejected. GraphQL Yoga's persisted operations plugin, which its documentation describes as a mechanism for preventing the execution of arbitrary operation documents, follows Apollo's APQ format for sending hashes by default, and its example refuses an operation outside the store with the message PersistedQueryOnly.

Persisted is not the same as trusted

Apollo Server's automatic persisted queries are a performance feature. Its documentation says a persisted query is a query string cached on the server with its SHA-256 hash, that each unique query string must first be sent to the server at least once, and that after any client sends one, every client that executes that query can benefit.

It says Apollo Server supports APQ without any additional configuration, and that setting persistedQueries to false disables it entirely. The GraphQL.js guide warns against confusing trusted documents with APQ, which it calls "a network optimization potentially open for anyone to use".

The workbook's last row therefore sends four requests: the hash of an approved document, which should run; an unapproved document, which should be refused; an unapproved document together with its own hash, the way an APQ client registers one; and that hash alone.

If the third returns data, the server ran a document outside the allowlist. If the fourth then returns data too, it also stored that document, the way Apollo's APQ page describes.

The GraphQL.js guide marks introspection control unnecessary, and complexity limits possibly a development-only concern, once only trusted documents are allowed. Access control is not on that list. An approved document can still be sent with another tenant's ID in its variables, so the census rows apply to every approved document.

How to use the schema and resolver workbook

The workbook on this page is written for your own API, in an environment you control, with test accounts you created.

Part A is the introspection decision. Part B has ten test rows, each with where to look, what to send, the result to expect when the control is in place and the source behind that expectation, and space for your answers. Part C is a worked example on paper for an invented two-tenant schema, with its requests written out.

  • Create two test tenants, each with two users in different roles, and seed each with records the other tenant should never see. Use staging if it runs the same build and configuration as production.
  • Write the expected result for every row before you send anything, from your own rules.
  • For the alias, batching, depth, score and page size rows, record the configured limit and send one request just over it. One refused request answers the question, and more requests only add load.
  • Use read-only queries for every limit row. Where a row concerns a mutation, such as a sign-in or code check, read its limit from configuration instead of sending attempts.
  • If production accepts trusted documents only, run rows B1 to B9 where ad hoc documents are admitted for test accounts, or send approved documents with test variables, and run B10 where ordinary callers would.
  • Keep each request and response with tokens, session cookies and personal details removed. Record where a secret lives, never its value.
  • Run Part B again when the schema changes: a new type, a new field that returns tenant data, a new mutation, or a new server version.

What a review of your own schema cannot show

A completed workbook shows how the deployed server answered the requests you sent, on the day you sent them, for the paths you listed.

A field added after that day, a resolver that reaches tenant data through a helper the census did not list, or a cache shared between tenants inside the data layer will not appear unless one of your requests happens to cross it.

Some surfaces sit outside request-by-request rows. graphql.org notes that WebSockets or server-sent events are often used for longer-lived subscription operations, and the workbook's HTTP rows do not exercise those connections. Where a gateway composes several services, whether each service also answers on its own address is a question the workbook asks at the top but cannot settle from the gateway. A limit that rejects one oversized request says nothing about how the server behaves under heavy traffic.

A clean result is a result for the rows you ran. OWASP's API reconnaissance test, WSTG-APIT-01, sits in the edition of its testing guide that the site labels Latest and says may frequently change; as read on 14 November 2026, it tells a tester on a time-boxed engagement to request schemas or exported schemas when introspection is disabled for a GraphQL API in scope.

In this page's view, a schema hidden from the internet is still where a review done with your permission starts.

Where a Clever Ops test fits

This guide is informational.

Nothing on it is a test of GraphQL itself, of a GraphQL server library or of any vendor's platform, and the workbook is for your own team to keep.

If you want your GraphQL API itself tested, that work belongs in a scoped web application and API penetration test. The service signs in to your custom web application with test accounts in every role and tests the API behind it, and the GraphQL API your own front end calls is covered as part of the application.

An API that partners or a mobile app reach with their own keys or tokens is a separate surface with its own scope, and the mobile app is outside the service. As with the two test tenants in the workbook, the scope asks for two test accounts per role, plus accounts in two customer organisations where your application serves more than one.

A staging copy that matches production is preferred, and read-only code access can be added for a closer look at the riskiest areas.

Load and denial-of-service testing is referred to a load-testing specialist, with your host's written approval. If Clever Ops built or hosts the application, the work is a security review rather than an independent test, and the report names who built it and who hosts it. The report is not a certificate or a compliance opinion.

Frequently asked questions

It depends on who the API serves, in the sources quoted here. The GraphQL specification says a GraphQL service supports introspection over its schema. graphql.org says APIs that only serve first-party clients may forbid it outside development, and that disabling it will not be sufficient to obscure an API by itself. The OWASP GraphQL Cheat Sheet says leaving it enabled might be an intended configuration for an API designed to be consumed by external clients, but can also be an issue if the API was designed to be used internally only, and it lists disabling or restricting introspection, based on your needs, among the default configurations to change. Part A of the workbook records who your clients are as the basis for your own decision. In this page's view, exposure becomes a finding when a resolver answers a caller it should refuse.

Apollo Server's API reference documents an introspection constructor option. Its default value is true unless the NODE_ENV environment variable is set to production, and a nodeEnv option, if set, takes the place of NODE_ENV for the defaults that depend on it. This page's advice is to set the option explicitly if you want the same answer in every environment, then confirm it from outside with one introspection request sent with no session.

Not entirely. graphql.org says that even with introspection disabled, an attacker could ultimately infer the shape of an entire schema by running numerous operations with incorrect field names, and its section on error messages explains that validation errors can come with suggestions. GraphQL.js has a hideSuggestions option, available in v17, in v16 from v16.15.0 and in v15 from v15.11.0, with suggestions on by default. Apollo Server has hideSchemaDetailsFromClientErrors, false by default, which Apollo recommends enabling in production. GraphQL Yoga's documentation uses a GraphQL Armor plugin to block them.

A cap on how deeply fields can nest in one operation. graphql.org's security page recommends limiting maximum depth, notes that many implementations can reject a request over the limit before execution begins, and recommends a separate, smaller limit for nested lists. The GraphQL.js production guide's example adds depthLimit(10) from the graphql-depth-limit package to the validation rules. Depth does not catch a wide, shallow query. graphql.org's example of one aliases a single field many times, and the same page also covers limits on aliases and batches, and query complexity analysis.

No. Apollo Server's documentation says a query string is persisted once a client sends it with its hash, and that after any client sends a query string to persist, every client that executes that query can benefit. The GraphQL.js production guide warns against confusing trusted documents with APQ, which it calls "a network optimization potentially open for anyone to use". Trusted documents, as graphql.org describes them, are an allowlist of operations, usually ones your developers wrote and approved through code review, and the server will only execute requests for known document IDs.

OWASP describes exactly that. Its API4:2023 entry has a GraphQL endpoint whose traditional rate limit is bypassed by many upload operations in one batched request, and its GraphQL Cheat Sheet says batching attacks will likely bypass rate limits in proxies or gateways that count raw requests. graphql.org says applying rate limits within the business logic layer is generally recommended. Apollo Server refuses array-formatted batches unless allowBatchedHttpRequests is enabled, and GraphQL Yoga has batching disabled by default.

Scope the right test for your application

Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.