Launch GraphOS Studio

Enterprise features for the Apollo Router

Available with GraphOS Enterprise

The Apollo Router provides expanded security, performance, and customization features for organizations with a GraphOS Enterprise plan.

You can test out these features for free with an Enterprise trial.

List of features

Articles specifically about Enterprise features are marked with a icon in the left navigation.

For details on these features, see this blog post in addition to the documentation links above.

Enabling Enterprise features

To enable support for the Apollo Router's Enterprise features:

  • Your organization must have a GraphOS Enterprise plan.
  • You must run v1.12 or later of the Apollo Router. Download the latest version.
  • Your Apollo Router instances must connect to GraphOS with a graph API key and graph ref associated with your organization.
    • You connect your router to GraphOS by setting these environment variables when starting the router.
    • If your router already connects to your GraphOS Enterprise organization, no further action is required.

After enabling support, you can begin using all Enterprise features. Consult the documentation for each feature to learn more.

The Enterprise entitlement

Whenever your router instance starts up and connects to GraphOS, it fetches an entitlement, which is the credential that authorizes its use of Enterprise features:

Your Infrastructure
Fetches supergraph schema
and entitlement
Apollo Uplink
Apollo Router

A router instance retains its entitlement for the duration of its execution. If you terminate a router instance and then later start a new instance on the same machine, it must fetch a new entitlement.

Entitlements are served via Apollo Uplink, the same multi-cloud endpoint that your router uses to fetch its supergraph schema from GraphOS. Because of this, entitlements introduce no additional network dependencies, meaning your router's uptime remains unaffected.

A router instance's entitlement is valid for the duration of your organization's current subscription billing period (plus a grace period), even if the router temporarily becomes disconnected from GraphOS.

Entitlements with local development

While building your supergraph, you might run an Apollo Router instance on your local machine (such as with the rover dev command). It's likely that this router instance doesn't currently connect to GraphOS, because it obtains its supergraph schema via another mechanism. For example, rover dev performs composition locally after introspecting your running subgraphs, which might change frequently as you develop.

You can use Enterprise router features with a locally composed supergraph schema! To do so, your router must still connect to GraphOS to obtain its entitlement.


These steps work both for running the router executable directly (./router) and for running it via rover dev:

  1. Create a new variant for your supergraph that you'll use only to fetch Enterprise entitlements.

    • Give the variant a name that clearly distinguishes it from variants that track schemas and metrics.
    • Every team member that runs a router locally can use this same variant.
    • When you create this variant, publish a dummy subgraph schema like the following (your router won't use it):
    type Query {
    hello: String
  2. Create a graph API key for your supergraph and assign it the Contributor role.

    • We recommend creating a separate graph API key for each team member that will run the router locally.
  3. When you start up your local router with your usual command, set the APOLLO_GRAPH_REF and APOLLO_KEY environment variables for that command:

    APOLLO_GRAPH_REF="..." APOLLO_KEY="..." ./router --supergraph schema.graphql
    • The value of APOLLO_GRAPH_REF is the graph ref for the new, entitlement-specific variant you created (e.g., docs-example-graph@local-entitlements).
    • The value of APOLLO_KEY is the graph API key you created.
  4. Your router will fetch an Enterprise entitlement while using its locally composed supergraph schema.

Common errors

If your router doesn't successfully connect to GraphOS, it logs an error that begins with one of the following strings if any Enterprise features are enabled:

Error MessageDescription
Not connected to GraphOS.At least one of the APOLLO_KEY and APOLLO_GRAPH_REF environment variables wasn't set on router startup.
Entitlement not found.The router connected to GraphOS with credentials that are not associated with a GraphOS Enterprise plan.
Entitlement has expired.Your organization's GraphOS Enterprise subscription has ended. Your router will stop processing incoming requests at the end of the standard grace period.

Grace period for expired plans

If your organization terminates its GraphOS Enterprise subscription, your router's Enterprise entitlement is considered expired at the end of your final paid subscription period. GraphOS provides a grace period for expired entitlements so that you can disable Enterprise features before they produce breaking errors in your router.

If your router has an expired Enterprise entitlement, its behavior degrades according to the following schedule, if any Enterprise features are still enabled:

  • For the first 14 days after your entitlement expires, your router continues to behave as though it has a valid entitlement.
  • After 14 days, your router begins a soft outage: it continues processing client requests, but it emits logs and metrics that indicate it's experiencing an outage.
  • After 28 days, your router begins a hard outage. It no longer processes incoming client requests and continues emitting logs and metrics from the soft outage.

Your router resumes normal functioning whenever you renew your GraphOS Enterprise subscription or disable all Enterprise features.

You disable an Enterprise feature by removing all of its associated configuration keys from your router's YAML config file.

Federation version support
Edit on GitHubEditForumsDiscord