Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS 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 enables only Apollo Studio to initiate browser connections to it. If your serves data to other browser-based applications, you need to do one of the following in the cors section of your 's YAML config file:

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

    • Use this option if there is a known, finite list of web applications that consume your .
  • Add a regex that matches the origins of those web applications to the '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 is a public API with arbitrarily many web app consumers.
    • With this option enabled, the 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 serves exclusively non-browser-based clients, you probably don't need to modify the default CORS configuration.

Passing credentials

If your 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 enables allow_any_origin, your browser will refuse to send credentials.

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

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

Additionally, you'll need to configure the to forward the Cookie header to some (or all) of your s:

router.yaml
headers:
all:
request:
- propagate:
named: cookie

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.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: []
# Adds the Access-Control-Max-Age header
# Can be set to a duration in time units
# If not set, the header is not included
max_age: 2h

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 will add one with a value of "origin".

Previous
Traffic shaping
Next
CSRF prevention
Edit on GitHubEditForumsDiscord