Docs
Try Apollo Studio

Configuring CORS in the Apollo Router

Control browser access to your router


This article describes CORS configuration that's specific to the Apollo Router. For a more general introduction to CORS and common considerations, see the following sections:

  • Why use CORS?
  • Choosing CORS options for your project

By default, the Apollo Router enables only Apollo Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to do one of the following in the cors section of your router's YAML config file:

  • Add the origins of those web applications to the router's list of allowed origins.

    • Use this option if there is a known, finite list of web applications that consume your supergraph.
  • Add a regex that matches the origins of those web applications to the router's list of allowed origins.

    • This option comes in handy if you want to match origins against a pattern, see the example below that matches subdomains of a specific namespace.
  • Enable the allow_any_origin option.

    • Use this option if your supergraph is a public API with arbitrarily many web app consumers.
    • With this option enabled, the router sends the wildcard (*) value for the Access-Control-Allow-Origin header. This enables any website to initiate browser connections to it (but they can't provide cookies or other credentials).
  • You must use the origins + match_origins option if clients need to authenticate their requests with cookies.

The following snippet includes an example of each option (use either allow_any_origin, or origins + match_origins):

router.yaml
cors:
# Set to true to allow any origin
# (Defaults to false)
allow_any_origin: true
# List of accepted origins
# (Ignored if allow_any_origin is true)
# (Defaults to the Apollo Studio url: `https://studio.apollographql.com`)
#
# An origin is a combination of scheme, hostname and port.
# It does not have any path section, so no trailing slash.
origins:
- https://www.your-app.example.com
- https://studio.apollographql.com # Keep this so Apollo Studio can run queries against your router
match_origins:
- "https://([a-z0-9]+[.])*api[.]example[.]com" # any host that uses https and ends with .api.example.com

You can also disable CORS entirely by setting origins to an empty list:

router.yaml
cors:
origins: []

If your router serves exclusively non-browser-based clients, you probably don't need to modify the default CORS configuration.

Passing credentials

If your router requires requests to include a user's credentials (e.g., via cookies), you need to modify your CORS configuration to tell the browser those credentials are allowed.

You can enable credentials with CORS by setting the Access-Control-Allow-Credentials HTTP header to true.

Your router's config file must specify individual origins to support credentialed requests. If your router enables allow_any_origin, your browser will refuse to send credentials.

To allow browsers to pass credentials to the Apollo Router, set allow_credentials to true, like so:

router.yaml
cors:
origins:
- https://www.your-app.example.com
- https://studio.apollographql.com
allow_credentials: true

For examples of sending cookies and authorization headers from Apollo Client, see Authentication.

All cors options

The following snippet shows all CORS configuration defaults for the Apollo Router:

router.yaml
#
# CORS (Cross Origin Resource Sharing)
#
cors:
# Set to true to allow any origin
allow_any_origin: false
# List of accepted origins
# (Ignored if allow_any_origin is set to true)
#
# An origin is a combination of scheme, hostname and port.
# It does not have any path section, so no trailing slash.
origins:
- https://studio.apollographql.com # Keep this so Apollo Studio can still run queries against your router
# Set to true to add the `Access-Control-Allow-Credentials` header
allow_credentials: false
# The headers to allow.
# Not setting this mirrors a client's received `access-control-request-headers`
# This is equivalent to allowing any headers,
# except it will also work if allow_credentials is set to true
allow_headers: []
# Allowed request methods
methods:
- GET
- POST
- OPTIONS
# Which response headers are available to scripts running in the
# browser in response to a cross-origin request.
expose_headers: []

Response Vary header

A plugin may set a response Vary header. If, after all plugins are processed, there is no response Vary header, then the router will add one with a value of "origin".

Edit on GitHub
Previous
Overview
Next
CSRF prevention