Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Authenticating requests with the Apollo Router


Self-hosting the Apollo is limited to Apollo Enterprise plans. Other plan types use managed cloud routing with GraphOS.

Learn about Apollo plans.

When using the Apollo as the entry point to your federated , you have a few options for authenticating incoming client requests:

In fact, we recommend you combine all three strategies to create a more robust authentication system!

Authenticate in subgraphs

The simplest authentication strategy is to delegate authentication to your individual services.

ClientRouterSubgraphRequest with tokenRequest with tokenAuthenticate request with tokenClientRouterSubgraph

To pass Authentication headers from client requests to your s, add the following to your 's YAML configuration file:

- propagate:
named: authorization


  • Requires minimal changes to your configuration.
  • Can take advantage of existing authentication code in s, which is often tied to authorization logic for s.


  • Each that contributes to resolving a request needs to authenticate that request.
  • If s are written in different languages, maintaining consistent authentication code for each is complex.

Use the JWT Authentication plugin

As of Apollo v1.13, you can use the JWT Authentication plugin to validate JWT-based authentication tokens in your .

⚠️ This is an Enterprise feature of the Apollo . It requires an organization with a GraphOS Enterprise plan.

ClientRouterJWKS EndpointSubgraphRequest with JWTFetch key setPublic keysValidate JWTExtract claims in RhaiRequest with extracted claims in headersCheck claims on headersClientRouterJWKS EndpointSubgraph
- url:


  • The prevents unauthenticated requests from reaching your s.
  • The can extract claims from the JWT and pass them to your s as headers, reducing logic needed in your subgraphs.


  • It supports only JWT-based authentication with keys from a JWKS endpoint.

Use a coprocessor

If you have a custom authentication strategy, you can use a coprocessor to implement it.

⚠️ This is an Enterprise feature of the Apollo . It requires an organization with a GraphOS Enterprise plan.

ClientRouterCoprocessorSubgraphRequest with tokenRequest with headers and contextValidate requestRespond { control: { break: 401 } }Respond { control: "continue" }Can also add new headersalt[Request is invalid][Request is valid]Request with new headersCheck claims on headersClientRouterCoprocessorSubgraph
headers: true

This example coprocessor is written in Node.js and uses Express:

const app = express();
app.use(bodyParser.json());'/', async (req, res) => {
const {headers} = req.body;
const token = headers.authorization;
const isValid = await validateToken(token);
if (!isValid) {
control: {break: 401}
} else {
control: 'continue',
headers: {'x-claims': extractClaims(token)}


  • You can implement any authentication strategy in any language or framework, as long as the coprocessor provides an HTTP endpoint.
  • You can use the coprocessor to add headers to requests, which can be used by your s for additional authorization.


  • The initial lift of implementing a coprocessor is non-trivial, but once it's in place you can leverage it for any number of customizations.

Combining authentication strategies

You can combine the strategies to handle a number of authentication requirements and practice "defense-in-depth":

  1. Use a coprocessor to identify traffic using a legacy authentication strategy and convert legacy session tokens to JWTs.
  2. Use the JWT Authentication plugin to validate JWT-based authentication tokens.
  3. Forward JWTs to s for additional authorization.
Edit on GitHubEditForumsDiscord