Is introspection enabled by default?

Yes. Introspection is enabled by default. For production deployments, set introspection.enabled: false to hide the schema from unauthorized clients.

What does disabling introspection protect against?

Introspection returns the complete API schema including type names, field names, arguments, and descriptions. Disabling it prevents schema discovery, which attackers use to map an API and identify potential targets before attempting unauthorized access.

Can I allow introspection for internal tooling but not for production traffic?

Yes. If authentication is enabled, set authentication.ignore_introspection: true to bypass JWT validation for introspection queries. Internal tools can load the schema without a token. All data queries still require valid authentication.

What is the introspection secret for?

The introspection.secret adds a dedicated credential for introspection access. Tools must send this value in the Authorization header (without Bearer prefix). It keeps the introspection bypass from being open to anyone.

Should I use introspection bypass in production?

The authentication.ignore_introspection: true setting is intended for secure internal environments only. It is not recommended for production deployments where untrusted clients can reach the router.

Do I need to disable introspection if I have authentication enabled?

Not necessarily — authentication blocks unauthorized clients from reaching introspection and data queries alike. Disabling introspection adds defense in depth: if authentication is bypassed or misconfigured, the schema is still not exposed.

GraphQL Introspection Control | Cosmo by WunderGraph

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

For production: set introspection.enabled: false in router YAML. All introspection queries return an error. The schema is hidden from clients.
For internal environments with authentication enabled: set authentication.ignore_introspection: true. Introspection queries bypass JWT validation. All data queries still require a valid token.
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.
Combine the settings per environment. introspection.enabled and ignore_introspection work independently.

Authentication bypass is for secure internal environments only. Not for production.

Introspection Control

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

Disable introspection: introspection.enabled: false
Bypass auth for introspection: authentication.ignore_introspection: true
Dedicated introspection secret: introspection.secret: 'your_secret'

How introspection control works in Cosmo Router

01

Intercepts before execution.

Detect

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

02

Error returned, no schema leaked.

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

Auth skipped for introspection only.

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

Separate credential for schema access.

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.

Start Free Read the Docs

Hide your schema from unauthorized clients