Enterprise features for the Apollo Router

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

List of features

• Real-time updates via GraphQL subscriptions
• Authentication of inbound requests via JSON Web Token (JWT)
• Authorization of specific fields and types through the @requiresScopes and @authenticated directives
• Redis-backed distributed caching of query plans and persisted queries
• Custom request handling in any language via external coprocessing
• Mitigation of potentially malicious requests via operation limits and safelisting with persisted queries

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

Enabling Enterprise features

To enable support for Apollo Router 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.
  • Certain Enterprise features might require a later router version. See a particular feature's documentation for details.
• 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 license

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

A router instance retains its license 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 license.

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

A router instance's license 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.

Licenses 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 license.

Setup

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 licenses.

   • 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):
   GraphQL

   1
   type Query {
   2
     hello: String
   3
   }

   Copy

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:

   Bash

   1
   APOLLO_GRAPH_REF="..." APOLLO_KEY="..." ./router --supergraph schema.graphql

   Copy
   • The value of APOLLO_GRAPH_REF is the graph ref for the new, license-specific variant you created (e.g., docs-example-graph@local-licenses).
   • The value of APOLLO_KEY is the graph API key you created.

4. Your router will fetch an Enterprise license 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:

Grace period for expired plans

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

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

• For the first 14 days after your license expires, your router continues to behave as though it has a valid license.
• 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.