GraphQL Introspection Control | Cosmo by WunderGraph - WunderGraph

Hide your schema from unauthorized clients

Disable introspection in production. Selectively bypass authentication for schema tooling in internal environments. Add a dedicated introspection secret for access control.

Introspection Control

The problem

Introspection is a complete schema map for anyone who asks

Every type, field, and relationship in your API is visible to any client that sends an introspection query. In production, that visibility is a security liability.

Introspection reveals the complete API map

GraphQL introspection returns every type, field, query, mutation, and subscription in the schema — including descriptions. Attackers use this to understand API structure and identify targets before probing for vulnerabilities.

Internal tooling needs introspection, production does not

Schema-aware tools like Postman, Apollo Studio, and custom IDEs query introspection to load the schema. Teams running these tools in authenticated environments still need introspection to function, even when it should be off in production.

All-or-nothing authentication blocks tooling without protecting data

Enabling authentication on the router blocks introspection in internal tooling, requiring developers to configure tokens just to load a schema. Disabling authentication to unblock tooling removes protection from data queries.

Our solution

Three controls for introspection access

Disable introspection for production, bypass authentication for internal tooling, and add a secret to protect that bypass.

Configure per environment

  1. For production: set introspection.enabled: false in router YAML. All introspection queries return an error. The schema is hidden from clients.
  2. For internal environments with authentication enabled: set authentication.ignore_introspection: true. Introspection queries bypass JWT validation. All data queries still require a valid token.
  3. To protect the bypass: set introspection.secret with a dedicated value. Clients include this value in the Authorization header (without Bearer prefix) to access introspection.
  4. Combine the settings per environment. introspection.enabled and ignore_introspection work independently.

Before & After

Before With Cosmo
Schema visible to any client via introspection Introspection disabled — schema hidden from clients
Introspection blocked by authentication in internal tooling ignore_introspection: true — tooling works, data stays protected
No way to protect introspection independently of authentication introspection.secret adds a dedicated credential for schema access
Same production config prevents tooling access Toggle-based control per environment

Config options

Three settings

How introspection control works in Cosmo Router

01

Detect

The router recognizes introspection queries — requests for the schema itself — and applies the configured introspection rules before returning any schema data.

02

Disable

When introspection.enabled: false, the router returns an error for any introspection query without executing it. No schema information is returned. This is the recommended setting for production deployments.

03

Bypass auth

When authentication.ignore_introspection: true, the router skips JWT validation for introspection queries only. All other queries still require a valid token. Use this in internal environments where authentication is required for data but tooling needs schema access.

04

Add a secret

Set introspection.secret with a dedicated value. Tools must include this value in the Authorization header without a Bearer prefix to access introspection. It protects the bypass with a dedicated credential.

Introspection controls

Right access in the right environment

Production locked down. Internal tooling functional.

Production: introspection off

One line disables all introspection queries. The schema is not returned to any client. This is the recommended setting for any production deployment where the schema should not be publicly discoverable.

Internal: bypass auth for tooling

Teams using schema-aware tools in secure internal environments can set ignore_introspection: true. Tools load the schema without authentication tokens. Data queries still require valid JWT tokens.

Dedicated introspection secret

Configure a separate secret for introspection access. Clients send it in the Authorization header (no Bearer prefix). This keeps the auth bypass from being open to anyone.

Defense in depth

Disabling introspection adds a layer of protection even when authentication is enabled. If authentication is misconfigured or bypassed, the schema is still not exposed. Use both for production deployments.

Control who can see your schema

Disable introspection in production. One line of YAML.

FAQ

Introspection Control on Cosmo Router