skilld
All skills
apollographql avatar

/apollo-router

@f13ff34 official
by Apollo GraphQLapollographql/skills115 stars
13

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/apollographql/skills/apollo-router

This session only. Nothing lands on disk.

divergence-map.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Apollo Router v1 ↔ v2 Config Divergence Map

This document tracks every configuration section where v1 and v2 schemas differ in ways that break parsing or change behavior. All templates in this skill branch on these differences.

CORS

Aspect v1 v2
Origins cors.origins: [...] (flat list) cors.policies: [{ origins: [...] }] (array of policy objects)
Headers cors.allow_headers Same key, but inside each policy or at global level
Methods cors.methods Same, inheritable per-policy
Max Age Duration string (for example: cors.max_age: 24h) Same format (duration string)
Credentials cors.allow_credentials Same, inheritable per-policy

See: templates/v1/sections/cors.yaml vs templates/v2/sections/cors.yaml

JWT Authentication

Aspect v1 v2
Issuer field issuer: <string> (singular) issuers: [<string>, ...] (plural, array)
Poll interval poll_interval supported Same

[!CAUTION] issuer is a v1 field. In v2, always use issuers (array).

See: templates/v1/sections/auth.yaml vs templates/v2/sections/auth.yaml

Authorization Directives (@authenticated / @requiresScopes / @policy)

The enable key is the same in both versions — what diverges is availability and the claims context key read by coprocessors.

Aspect v1 v2
Enable key authorization.directives.enabled (default true) Same
Minimum version v1.29.1+ (GraphOS-connected) All v2; Developer/Standard plans require v2.6.0+
Claims context key apollo_authentication::JWT::claims apollo::authentication::jwt_claims

[!NOTE] Directives are on by default — config only disables them. They live in subgraph schemas, not router.yaml.

Persisted Queries (Safelisting)

Distinct from APQ. The config key changed across v1 preview → GA:

Aspect v1.25.0–v1.32.0 (preview) v1.32.0+ / all v2 (GA)
Config key preview_persisted_queries persisted_queries
local_manifests key experimental_local_manifests (v1.50.0–v1.54) local_manifests (v1.55.0+)

[!CAUTION] Enabling persisted_queries.safelist requires apq.enabled: false — APQ and safelisting are mutually exclusive.

Operation Limits

Aspect v1 (early) v1 (1.17+) / v2
Config key preview_operation_limits limits

Both v1.17+ and v2 use limits. Only very old v1 installs use preview_operation_limits.

Connectors (Router v2 only)

Connectors are a Router v2 feature. The relevant schema difference is early v2 preview vs current v2 GA:

Aspect v2.0.x (preview) v2.1+ (GA)
Config key preview_connectors connectors
Subgraph/source mapping subgraphs.<name>.sources.<source> sources.<subgraph>.<source> (dot notation)

Only relevant if using Apollo Connectors for REST API integration.

Telemetry

Aspect v1 v2
experimental_when_header Supported Removed — use custom telemetry events
Metric names Legacy names OpenTelemetry naming conventions
Apollo reporting FTV1 by default OTLP by default (otlp_tracing_sampler defaults to 1.0)
Prometheus exporter telemetry.exporters.metrics.prometheus Same path

Telemetry templates are largely compatible. v2 uses OTLP-first reporting.

Traffic Shaping

Schema is identical between v1 and v2. Behavioral change: v2 returns HTTP 429 for rate-limited requests (restored in v2.1.0 after briefly returning 503 in v2.0.0).

Context Keys (Coprocessors)

Multiple context keys were renamed in v2. Only relevant if configuring coprocessors.

v1 Key v2 Key
apollo_authentication::JWT::claims apollo::authentication::jwt_claims
apollo_operation_id apollo::operation_id

[!TIP] If using coprocessors during migration, set context: deprecated to preserve v1 key names while transitioning.

Key Documentation References

Topic URL
v2 YAML Reference https://www.apollographql.com/docs/graphos/routing/configuration/yaml
v1 → v2 Upgrade Guide https://www.apollographql.com/docs/graphos/routing/upgrade/from-router-v1
What's New in v2 https://www.apollographql.com/docs/graphos/routing/about-v2
CORS (v2) https://www.apollographql.com/docs/graphos/routing/security/cors
JWT Auth https://www.apollographql.com/docs/graphos/routing/security/jwt
Authorization Directives https://www.apollographql.com/docs/graphos/routing/security/authorization
Persisted Query Safelisting https://www.apollographql.com/docs/graphos/platform/security/persisted-queries
Request Limits https://www.apollographql.com/docs/graphos/routing/security/request-limits
Traffic Shaping https://www.apollographql.com/docs/graphos/routing/performance/traffic-shaping
v1 EOL Announcement https://www.apollographql.com/blog/end-of-support-for-router-v1-x-long-term-support-lts-policy-update

Source: SKILL.md on GitHub

Third-party checks

2 warnings16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is a configuration generator and guide for Apollo Router. It implements robust security best practices by default, including environment variable interpolation for sensitive data, disabling developmental features (introspection/sandbox) in production, and providing a validation checklist. No malicious patterns, data exfiltration, or unauthorized command execution risks were found.

  • Socket16d

    1 alert: gptAnomaly

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    26/26 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at f13ff34. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago

Capability

What it can do
Runs commands
metadata
{
  "author": "apollographql",
  "version": "2.5.0"
}
All 1 allowed tools
Bash(router:*) Bash(./router:*) Bash(rover:*) Bash(curl:*) Bash(docker:*) Read Write Edit Glob Grep
Other metadata
compatibility
Linux/macOS/Windows. Requires a composed supergraph schema from Rover or GraphOS.

Topics

  • apollo-router
  • graphql
  • federation
  • routing
  • yaml
  • telemetry
  • authentication
  • cors

README badge

README badge for apollographql/skills/apollo-router

What it does

Generates version-aware Apollo Router configuration (v1.x or v2.x) for federated GraphQL supergraphs, handling routing, authentication, CORS, telemetry, and connectors. Use this skill to set up Router with JWT auth, traffic shaping, operation limits, or to troubleshoot connectivity and performance issues.

Generated from the current SKILL.md.

Frequently asked

Does this skill support both Router v1 and v2?
Yes. The skill generates version-correct YAML for both v1.x and v2.x, which have incompatible config schemas. You must select your target version before generating any config.
Can I use this skill to configure Connectors?
Yes, but only for Router v2. Connectors (REST API integration) are a v2-only feature available in GA. The skill will not offer Connectors as an option if you select v1.
What do I need before I can run the generated config?
You need either a composed `supergraph.graphql` file from Rover or GraphOS access via `APOLLO_KEY` and `APOLLO_GRAPH_REF`. The skill assumes you have reachable subgraphs and will validate the config against the Router binary if available.
Does this skill help with response caching?
Yes, but only for Router v2.6.0 and later. The skill requires you to identify which subgraphs serve user-specific data and how you identify users before generating cache config, to prevent data leakage.
Will the skill validate my generated config?
Yes. After generating or editing config, the skill runs a checklist and attempts to validate against `router config validate` if the Router CLI is available. It will report pass/fail for each checklist item.

Generated from the current SKILL.md. These answers refresh after source changes.