Try Apollo Studio

Configuring the Apollo Router

Command arguments and YAML config

For installation instructions, see the quickstart.

You run the Apollo Router with the following command (assuming you're in the same directory as the router executable):

./router --config router.yaml --supergraph supergraph-schema.graphql

Arguments for this command are described below.

Environment variables

If you're using the Apollo Router with managed federation, set these environment variables in its startup command:

APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router
Environment VariableDescription

The graph ref of the registered Apollo graph and variant that the router fetches its supergraph schema from.

Required if using managed federation.


The graph API key that the Apollo Router should use to authenticate with Apollo Studio when fetching its supergraph schema.

Required if using managed federation.

Command arguments

Where indicated, some of these arguments can also be set via an environment variable. Command-line arguments always take precedence over environment variables if an option is provided both ways.

Argument / Environment VariableDescription
-s / --supergraph


The absolute or relative path to the Apollo Router's supergraph schema.

To learn how to compose your supergraph schema with the Rover CLI, see the Federation quickstart.

Required if you are not using managed federation.

-c / --config


The absolute or relative path to the router's optional YAML configuration file.



The log level, indicating the most severe log message type to include. In ascending order of verbosity, can be one of: off, error, warn, info, debug, or trace.

The default value is info.

--hr / --hot-reload


If provided, the router watches for changes to its schema and configuration files and reloads them automatically without downtime.


The Apollo Uplink URL(s) that the Apollo Router should poll to fetch its latest supergraph schema.

This argument supports providing a comma-separated list of URLs.

For default behavior and possible values, see Apollo Uplink.


The amount of time between polls to Apollo Uplink.

The default value is 10s (ten seconds), which is also the minimum allowed value.


Prints out a JSON schema of the router's configuration file, including plugin configuration.

-V / --version

Prints out the Apollo Router's version.

YAML config file

The Apollo Router takes an optional YAML configuration file as input via the --config option. If the --hot-reload flag is also passed (or the APOLLO_ROUTER_HOT_RELOAD environment variable is set to true), the router automatically restarts when changes to the configuration file are made.

This file enables you to customize the router's behavior in many ways:

Listen address

By default, the router starts an HTTP server that listens on You can specify a different address like so:

# supergraph: Configuration of the Supergraph server
# The socket address and port to listen on

The router can also listen on a Unix socket (not supported on Windows):

# Absolute path to a Unix socket
listen: /tmp/router.sock

Endpoint path

By default, the router starts an HTTP server that exposes a POST/GET endpoint at path /.

You can change this path by setting server.path:

# supergraph: Configuration of the Supergraph server
# The path for GraphQL execution
# (Defaults to /)
path: /graphql

The path must start with /.

Path parameters and wildcards are supported. For example:

  • /:my_dynamic_prefix/graphql matches both /my_project_a/graphql and /my_project_b/graphql.
  • /graphql/* matches /graphql/my_project_a and /graphql/my_project_b.

Note: The router does not support wildcards in the middle of a path (e.g., /*/graphql). Instead, use a path parameter (e.g., /:parameter/graphql).


By default, the router does not resolve introspection queries. You can enable introspection like so:

# supergraph: Configuration of the Supergraph server
introspection: true

Landing page

By default, the router displays a landing page if you access its endpoint path via your browser. You can override this behavior to disable the landing page like so:

enabled: false


You can enable the sandbox by editing your configuration file. Make sure introspection is enabled as well, and that homepage is disabled:

enabled: true
# make sure you enable introspection
introspection: true
# make sure homepage is disabled
enabled: false

Subgraph routing URLs

By default, the Apollo Router extracts the routing URL for each of your subgraphs from the composed supergraph schema you provide it. In most cases, no additional configuration is required.

However, if you do need to override a particular subgraph's routing URL (for example, to handle changing network topography), you can do so in your YAML configuration file with the override_subgraph_url option:

accounts: http://localhost:8080

In this example, the accounts subgraph URL is overridden to point to http://localhost:8080. The URL specified in the supergraph schema is ignored.

Subgraphs not included in the override_subgraph_url list continue to use the routing URL specified in the supergraph schema.

HTTP header rules

See Sending HTTP headers to subgraphs.

Cross-Origin Resource Sharing (CORS)

See Configuring CORS in the Apollo Router.

OpenTelemetry tracing

See Tracing in the Apollo Router.

Automatic persisted queries (APQ)

Automatic Persisted Queries (APQ) enable GraphQL clients to send a server the hash of their query string, instead of the query string itself. This can significantly reduce network usage for very large query strings. The Apollo Router automatically supports APQ via its in-memory cache. No configuration options are supported at this time. Support for external data stores like Redis and Memcached will be supported in a future release.

For more information on APQ, including client configuration, see this article.


You can customize the Apollo Router's behavior with plugins. Each plugin can have its own section in the configuration file with arbitrary values:

var1: "hello"
var2: 1

Variable expansion

You can reference variables directly in your YAML file. This is useful for referencing secrets without including them in the file.

Only environment variable expansion is currently supported, and variables must be prefixed with env.

Unix-style expansion is used. For example:

  • ${env.ENV_VAR_NAME} expands to the value of environment variable ENV_VAR_NAME.
  • ${env.ENV_VAR_NAME:-some_default} expands to the value of environment variable ENV_VAR_NAME, or falls back to the value some_default if the environment variable is not defined.
  • ${file.a.txt} expands to the content of a.txt.
  • ${file.a.txt:-some_default} expands to the content of a.txt, or falls back to the value some_default if the file does not exist.

Variable expansions are valid only for YAML values, not keys:

listen: "${env.MY_LISTEN_ADDRESS}"
password: "${env.MY_PASSWORD}"

Reusing configuration

You can reuse parts of your configuration file in multiple places using standard YAML aliasing syntax:

- insert: &insert_custom_header
name: "custom-header"
value: "something"
- insert: *insert_custom_header

Here, the name and value entries under &insert_custom_header are reused under *insert_custom_header.

Configuration awareness in your text editor

The Apollo Router can generate a JSON schema for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assist.

Generate the schema with the following command:

./router --schema > configuration_schema.json

After you generate the schema, configure your text editor. Here are the instructions for some commonly used editors:

Edit on GitHub
Federation version support