docs: add docs for introspection auth bypass (#166)

* feat: add docs for introspection auth bypass

* fix: use better wording to describe default behaviour

* chore: update docs to latest feature changes + improve wording

* chore: add new config settings to global config

Author: dkorittki

docs/router/authentication-and-authorization.mdx

@@ -56,6 +56,54 @@ The router configuration facilitates the setup of multiple JWKS (JSON Web Key Se
 
 For more information on the attributes, visit the auth configuration parameter section page [here](/router/configuration#authentication).
 
+### Disabling Authentication for Introspection Operations
+
+Cosmo Router supports bypassing authentication for introspection queries.
+
+This is useful, for example, when you want to configure client tooling from within a secured environment without requiring authentication tokens.
+Instead of having to disable authentication altogether, this feature allows you to keep the configuration as close to production as possible while still using introspection queries easily.
+Additionally, you can define a dedicated secret to authenticate introspection queries.
+
+<Warning>
+This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment.
+By default, introspection queries are not excluded from authentication.
+</Warning>
+
+To enable this feature, add the following section to your router configuration:
+
+<CodeGroup>
+  ```yaml config.yaml
+  authentication:
+    ignore_introspection: true # default is false
+    # other auth settings here
+  ```
+</CodeGroup>
+
+Now, when you send an introspection query, you won't need to provide an authentication token.
+
+```bash
+curl -X POST http://localhost:3002/graphql \
+  --header "Content-Type: application/json" \
+  --data '{"query": "{ __schema { types { name } } }"}'
+```
+
+Optionally, you can set a dedicated secret for introspection queries.
+
+<CodeGroup>
+  ```yaml config.yaml
+  introspection:
+    secret: 'dedicated_secret_for_introspection'
+  ```
+</CodeGroup>
+
+When a secret is set, you must include it in the `Authorization` header (without a Bearer prefix).
+
+```bash
+curl -X POST http://localhost:3002/graphql \
+  --header "Content-Type: application/json" \
+  --header "Authorization: dedicated_secret_for_introspection" \
+  --data '{"query": "{ __schema { types { name } } }"}'
+```
 
 
 ## Old Router configuration (\< 0.168.1)

docs/router/configuration.mdx

@@ -134,7 +134,7 @@ The following sections describe each configuration in detail with all available
 | CONTROLPLANE_URL                 | controlplane_url                 | <Icon icon="square-check" iconType="solid" /> | The controlplane url. Not required when a static execution config is provided.                                                                                                                     | https://cosmo-cp.wundergraph.com |
 | PLAYGROUND_ENABLED               | playground_enabled               | <Icon icon="square" />                        | Enables the GraphQL playground on (`$LISTEN_ADDR/`)                                                                                                                                                | true                             |
 | PLAYGROUND_PATH                  | playground_path                  | <Icon icon="square" />                        | The path where the playground is served                                                                                                                                                            | "/"                              |
-| INTROSPECTION_ENABLED            | introspection_enabled            | <Icon icon="square" />                        | Enables the GraphQL introspection                                                                                                                                                                  | true                             |
+| INTROSPECTION_ENABLED            | introspection_enabled            | <Icon icon="square" />                        | Enables the GraphQL introspection (deprecated, use `introspection.enabled` instead)                                                                                                                                                                | true                             |
 | QUERY_PLANS_ENABLED              | query_plans_enabled              | <Icon icon="square" />                        | The Router can return Query plans as part of the response, which might be useful to understand the execution.                                                                                      | true                             |
 | LOG_LEVEL                        | log_level                        | <Icon icon="square" />                        | The log level to use. Allowed levels are `"debug"`, `"info"`, `"warn"`, `"error"`, `"panic"`, `"fatal"`.                                                                                     | info                             |
 | JSON_LOG                         | json_log                         | <Icon icon="square" />                        | Render the log output in JSON format (true) or human readable (false)                                                                                                                              | true                             |
@@ -173,6 +173,11 @@ liveness_check_path: "/health/live"
 router_config_path: ""
 ```
 
+<Warning>
+  `introspection_enabled` is a deprecated flag.
+  Please use `introspection.enabled` instead.
+</Warning>
+
 ## Config watcher hot reloading
 
 The router is capable of reloading itself using an updated config without a full process restart. You can trigger a reload in one of two ways:
@@ -304,6 +309,25 @@ graph:
   token: "<your-graph-token>"
 ```
 
+## Introspection
+
+Overall configuration for managing introspection queries on this Router.
+
+| Environment Variable  | YAML           | Required               | Description                                                                                                                                   | Default Value |
+| --------------------- | -------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| INTROSPECTION_ENABLED | enabled        | <Icon icon="square" /> | Enable or disable introspection queries                                                                                                       | true          |
+| INTROSPECTION_SECRET  | secret         | <Icon icon="square" /> | Optional, dedicated secret used for instrospection authentication. Only used when `authentication.ignore_introspection` is set to `true`.     |               |
+
+### Example YAML config:
+
+```yaml config.yaml
+version: "1"
+
+introspection:
+  enabled: true
+  secret: "dedicated_secret_for_introspection"
+```
+
 ## MCP (Model Context Protocol)
 
 The Model Context Protocol (MCP) server allows AI models to discover and interact with your GraphQL API in a secure way.
@@ -1506,6 +1530,21 @@ authentication:
         name: X-Authorization
 ```
 
+### Bypass Introspection Authentication
+
+This is useful when you want to bypass authentication for introspection queries,
+for example let certain tools introspect the schema without requiring authentication token.
+
+<Warning>
+  This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment.
+  By default, introspection queries are not excluded from authentication.
+  Also consider setting `introspection.secret` for a static secret dedicated to introspection queries.
+</Warning>
+
+| Environment Variable | YAML                 | Required               | Description                         | Default Value    |
+| -------------------- | -------------------- | ---------------------- | ----------------------------------- | ---------------- |
+|                      | ignore_introspection | <Icon icon="square" /> | Bypass introspection authentication | false            |
+
 ### Old Authentication Config (Router Version \< 0.XXX.X)
 
 ### Provider

docs/router/security/hardening-guide.mdx

@@ -12,7 +12,8 @@ By default introspection is enabled. The following configuration should be appli
 
 <CodeGroup>
   ```yaml router.yaml
-  introspection_enabled: false
+  introspection:
+    enabled: false
   ```
 </CodeGroup>