/apollo-router

name: apollo-router
description: >
  Version-aware guide for configuring and running Apollo Router for federated GraphQL supergraphs.
  Generates correct YAML for both Router v1.x and v2.x. Use this skill when:
  (1) setting up Apollo Router to run a supergraph,
  (2) configuring routing, headers, or CORS,
  (3) implementing custom plugins (Rhai scripts or coprocessors),
  (4) configuring telemetry (tracing, metrics, logging),
  (5) troubleshooting Router performance or connectivity issues,
  (6) securing the graph with JWT, declarative field-level authorization directives, or persisted-query safelisting,
  (7) managing router.yaml as version-controlled config with CI/CD validation.
license: MIT
compatibility: Linux/macOS/Windows. Requires a composed supergraph schema from Rover or GraphOS.
metadata:
  author: apollographql
  version: "2.5.0"
allowed-tools: Bash(router:*) Bash(./router:*) Bash(rover:*) Bash(curl:*) Bash(docker:*) Read Write Edit Glob Grep

Apollo Router Config Generator

Apollo Router is a high-performance graph router written in Rust for running Apollo Federation 2 supergraphs. It sits in front of your subgraphs and handles query planning, execution, and response composition.

**This skill generates version-correct configuration.** Router v1 and v2 have incompatible config schemas in several critical sections (CORS, JWT auth, connectors). Always determine the target version before generating any config.

Step 1: Version Selection

Ask the user **before generating any config**:

Which Apollo Router version are you targeting?

  [1] Router v2.x (recommended — current LTS, required for Connectors)
  [2] Router v1.x (legacy — end-of-support announced, security patches only)
  [3] Not sure — help me decide

If the user picks **[3]**, display:

Quick guide:

  • Pick v2 if: you're starting fresh, using Apollo Connectors for REST APIs,
    or want backpressure-based overload protection.
  • Pick v1 if: you have an existing deployment and haven't migrated yet.
    Note: Apollo ended active support for v1.x. The v2.10 LTS (Dec 2025)
    is the current baseline. Migration is strongly recommended.

  Tip: If you have an existing router.yaml, you can auto-migrate it:
    router config upgrade router.yaml

Store the selection as `ROUTER_VERSION=v1|v2` to gate all subsequent template generation.

Step 2: Environment Selection

Ask: **Production** or **Development**?

• **Production**: security-hardened defaults (introspection off, sandbox off, homepage off, subgraph errors hidden, auth required, health check on)
• **Development**: open defaults (introspection on, sandbox on, errors exposed, text logging)

Load the appropriate base template from:

• `templates/{version}/production.yaml`
• `templates/{version}/development.yaml`

Step 3: Feature Selection

Ask which features to include:

• [ ] JWT Authentication
• [ ] Declarative Authorization (field-level `@authenticated` / `@requiresScopes` / `@policy` directives — requires GraphOS + request claims)
• [ ] CORS (almost always yes for browser clients)
• [ ] Operation Limits
• [ ] Traffic Shaping / Rate Limiting
• [ ] Telemetry (Prometheus, OTLP tracing, JSON logging)
• [ ] APQ (Automatic Persisted Queries — performance/bandwidth only, NOT a security control)
• [ ] Persisted Query Safelisting (GraphOS PQL operation allowlist — a security control; distinct from APQ)
• [ ] Connectors (REST API integration — Router v2 only; GA key is `connectors`, early v2 preview key was `preview_connectors`)
• [ ] Subscriptions
• [ ] Header Propagation
• [ ] Response Caching (entity + root field caching with Redis — Router v2 only, v2.6.0+)

Step 4: Gather Parameters

For each selected feature, collect required values.

• Use section templates from `templates/{version}/sections/` for `auth`, `cors`, `headers`, `limits`, `telemetry`, and `traffic-shaping`.
• For Connectors in v2, use `templates/v2/sections/connectors.yaml` as the source.
• For APQ and subscriptions, copy the snippet from the selected base template (`templates/{version}/production.yaml` or `templates/{version}/development.yaml`) or from references.
• Only offer Connectors when `ROUTER_VERSION=v2`.

CORS

• List of allowed origins (never use `"*"` for production)

JWT Authentication

• JWKS URL
• Issuer(s) — note: v1 uses singular `issuer`, v2 uses plural `issuers` array

Declarative Authorization (field-level)

> Field- and type-level access control enforced **in the router**, via the `@authenticated`, `@requiresScopes`, and `@policy` directives applied in subgraph schemas. This is the layer that the global `authorization.require_authentication` gate cannot express. It is a **GraphOS feature** (Enterprise; Developer/Standard plans require Router v2.6.0+) and requires a router connected to GraphOS. Directives are **enabled by default** — config only turns them *off*.

Confirm prerequisites before recommending these:

• **Router connected to GraphOS** (Router v1.29.1+; Developer/Standard plans need v2.6.0+).
• **A claims source.** Directives evaluate the claims at the `apollo::authentication::jwt_claims` context key. Populate it via JWT authentication (configure that feature too) **or** a coprocessor that injects claims.
• **`@policy` additionally requires a Supergraph plugin** (Rhai script or coprocessor) to evaluate each policy — the router extracts required policies into `apollo::authorization::required_policies` but does not decide them itself.

Ask:

• **Which fields/types need protection, and at what level?** (`@authenticated` = any valid identity; `@requiresScopes` = specific scopes; `@policy` = custom logic.)
• **Where do scopes/claims come from?** (JWT claims vs. coprocessor-injected.)

The directives live in the **subgraph schemas**, not in `router.yaml`. The router config only enables/disables the feature and (for `@policy`) wires the evaluating plugin. See `references/configuration.md` → Authorization.

Persisted Query Safelisting