GraphQL Summit is back for three days of insights, hands-on learning, and fun to celebrate the GraphQL community. Join us in San Diego Oct 3-5.
Try Apollo Studio

Customizations for the Apollo Router

Extend your router with custom functionality

You can write customizations for the Apollo Router to add functionality that isn't provided by default. For example, you can make an external call to fetch authentication data for each incoming request.

Customization types

The Apollo Router supports two types of customizations:

Use Rhai scripts if you can. Use a native rust plugin only if your customization needs to do any of the following:

  • Access Rust crates
  • Read or write to disk
  • Make network requests

How customizations work

Before you build a customization, it helps to understand how the Apollo Router handles each incoming GraphQL request. During each request's execution, three services in the router communicate with each other as shown:

ClientSupergraphServiceExecutionServiceSubgraphService(s)Sends requestInitiates queryplan executionInitiatessub-operationInitiatessub-operationInitiatessub-operationparAssembles andreturns responseReturns responseClientSupergraphServiceExecutionServiceSubgraphService(s)

As execution proceeds "left to right" from the SupergraphService to individual SubgraphServices, each service passes the client's original request along to the next service. Similarly, as execution continues "right to left" from SubgraphServices to the SupergraphService, each service passes the generated response for the client.

Apollo Router customizations can hook into any combination of these services and modify the request, response, and/or related metadata as they're passed along.

Service descriptions

Each Apollo Router service has a corresponding function that a customization can define to hook into that service:

Service /


Runs at the very beginning and very end of the request lifecycle.

Define supergraph_service if your customization needs to interact at the earliest or latest point possible. For example, this is a good opportunity to perform JWT verification before allowing a request to proceed further.



Handles initiating the execution of a query plan after it's been generated.

Define execution_service if your customization includes logic to govern execution (for example, if you want to block a particular query based on a policy decision).



Handles communication between the Apollo Router and your subgraphs.

Define subgraph_service to configure this communication (for example, to dynamically add HTTP headers to pass to a subgraph).

Whereas other services are called once per client request, this service is called once per subgraph that's required to resolve the client's request. Each call is passed a subgraph parameter that indicates the name of the corresponding subgraph

Each service has a request and response data-structure that holds:

  • A context object that was created at the start of the request and is propagated throughout the entire request lifecycle. It holds:
    • The original request from the client
    • A bag of data that can be populated by plugins for communication across the request lifecycle
  • Any other specific data to that service (e.g., query plans and downstream requests/responses)

Next, see the documentation for your preferred customization type.

Edit on GitHub
Client awareness
Rhai scripts