-
-
-### Runtime of GraphOS platform
-
-As the runtime of the [GraphOS platform](/graphos/get-started/concepts/graphos), a GraphOS Router gets the supergraph schema—the blueprint of the federated graphs—from the GraphOS control plane. It then executes incoming clients operations based on that schema.
-
-Unlike API gateways that offer capabilities to manage API endpoints, the router isn't based on URLs or REST endpoints. Rather, the router is a GraphQL-native solution for handling client APIs.
-
-### Enables Apollo Connectors
-
-Apollo Connectors are a core part of the router, enabling API orchestration with REST APIs.
-
-
-
-
-### Subgraph query planner
-
-Whenever your router receives an incoming GraphQL operation, it needs to figure out how to use your subgraphs to populate data for each of that operation's fields. To do this, the router generates a _query plan_:
-
-
-
-
-
-
-
-| - |
- Standard Check Behavior - (Legacy reference reporting) - |
-
- Enhanced Check Behavior - (Extended reference reporting) - |
-
|---|---|---|
| - -##### Enum value removal - - | -Removing any enum values is considered a breaking change if any operations use the enum. | -Removing enum values is only a breaking change if historical operations use the specific enum value(s) that were removed. | -
| - -##### Default argument changes for input object fields - - | -- Changing or removing a default argument is generally considered a breaking change, but changing or removing default values for input object fields isn't. - | -- Changing or removing default values for input object fields is considered a breaking change. - -You can [configure checks to ignore default values changes](/graphos/platform/schema-management/checks#ignored-conditions-settings). - - | -
| - -##### Nullable input object field removal - - | -Removing a nullable input object field is always considered a breaking change. | -Removing a nullable input object field is only considered a breaking change if the nullable field is present in historical operations. If the nullable field is always omitted in historical operations, its removal isn't considered a breaking change. | -
| - -##### Changing nullable input object fields to non-nullable - - | -Changing a nullable input object field to non-nullable is considered a breaking change. | -Changing a nullable input object field to non-nullable is only considered a breaking change if the field had a null value in historical operations. If the field was always a non-null value in historical operations, changing it to non-nullable isn't considered a breaking change. |
-
| Option / Environment Variable | +Description | +
|---|---|
| + +##### `-s` / `--supergraph` + +`APOLLO_ROUTER_SUPERGRAPH_PATH`, `APOLLO_ROUTER_SUPERGRAPH_URLS` + + | +
+
+The [supergraph schema](/federation/federated-types/overview#supergraph-schema) of a router. Specified by absolute or relative path (`-s` / `--supergraph + +> 💡 Avoid embedding tokens in `APOLLO_ROUTER_SUPERGRAPH_URLS` because the URLs may appear in log messages. + +Setting this option disables polling from Apollo Uplink to fetch the latest supergraph schema. + +To learn how to compose your supergraph schema with the Rover CLI, see the [Federation quickstart](/federation/quickstart). + +**Required** if you are _not_ using managed federation. If you _are_ using managed federation, you may need to set this option when following [advanced deployment workflows](/federation/managed-federation/deployment/#advanced-deployment-workflows). + + |
+
| + +##### `-c` / `--config` + +`APOLLO_ROUTER_CONFIG_PATH` + + | ++ +The absolute or relative path to the router's optional [YAML configuration file](#yaml-config-file). + + | + +
| + +##### `--apollo-key-path` + +`APOLLO_KEY_PATH` + + | ++ +The absolute or relative path to a file containing the Apollo graph API key for use with managed federation. + +⚠️ **This is not available on Windows.** + + | +
| + +##### `--dev` + + | +
+
+⚠️ **Do not set this option in production!**
+ +If set, a router runs in dev mode to help with local development. + +[Learn more about dev mode.](/graphos/routing/configuration/yaml#dev-mode-defaults) + + |
+
| + +##### `--hr` / `--hot-reload` + +`APOLLO_ROUTER_HOT_RELOAD` + + | ++ +If set, the router watches for changes to its configuration file and any supergraph file passed with `--supergraph` and reloads them automatically without downtime. This setting only affects local files provided to the router. The supergraph and configuration provided from GraphOS via Launches (and delivered via Uplink) are _always_ loaded automatically, regardless of this setting. + + | +
| + +##### `--log` + +`APOLLO_ROUTER_LOG` + + | ++ +The log level, indicating the _most_ severe log message type to include. In ascending order of verbosity, can be one of: `off`, `error`, `warn`, `info`, `debug`, or `trace`. + +The default value is `info`. + + | +
| + +##### `--license` + +`APOLLO_ROUTER_LICENSE_PATH`, `APOLLO_ROUTER_LICENSE` + + | +
+
+An offline GraphOS Enterprise license. Enables Enterprise router features when disconnected from GraphOS. + +An offline license is specified either as an absolute or relative path to a license file (`--license + +When not set, the router retrieves an Enterprise license [from GraphOS via Apollo Uplink](/router/enterprise-features/#the-enterprise-license). + +For information about fetching an offline license and configuring the router, see [Offline Enterprise license](/router/enterprise-features/#offline-enterprise-license). + + |
+
| + +##### `--apollo-uplink-endpoints` + +`APOLLO_UPLINK_ENDPOINTS` + + | +
+
+If using [managed federation](/federation/managed-federation/overview/), the Apollo Uplink URL(s) that the router should poll to fetch its latest configuration. Almost all managed router instances should _omit_ this option to use the default set of Uplink URLs. + +If you specify multiple URLs, separate them with commas (no whitespace). + +For default behavior and possible values, see [Apollo Uplink](/federation/managed-federation/uplink/). + + |
+
| + +##### `--apollo-uplink-timeout` + +`APOLLO_UPLINK_TIMEOUT` + + | ++ +The request timeout for each poll sent to Apollo Uplink. + +The default value is `30s` (thirty seconds). + + | +
| + +##### `--anonymous-telemetry-disabled` + +`APOLLO_TELEMETRY_DISABLED` + + | ++ +If set, disables sending anonymous usage information to Apollo. + + | +
| + +##### `--listen` + +`APOLLO_ROUTER_LISTEN_ADDRESS` + + | ++ +If set, the listen address of the router. + + | +
| + +##### `-V` / `--version` + + | ++ +If set, the router prints its version number, then exits. + + | +
| Environment Variable | +Description | +
|---|---|
| + +##### `APOLLO_GRAPH_REF` + + | ++ +The graph ref for the GraphOS graph and variant that the router fetches its supergraph schema from (e.g., `docs-example-graph@staging`). + +**Required** when using [managed federation](/federation/managed-federation/overview/), except when using an [offline license](#--license) to run the router. + + | +
| + +##### `APOLLO_KEY` + + | ++ +The [graph API key](/graphos/api-keys/#graph-api-keys) that the router should use to authenticate with GraphOS when fetching its supergraph schema. + +**Required** when using [managed federation](/federation/managed-federation/overview/), except when using an [offline license](#--license) to run the router or when using `APOLLO_KEY_PATH`. + + | +
| + +##### `APOLLO_KEY_PATH` + + | ++ +⚠️ **This is not available on Windows.** + +A path to a file containing the [graph API key](/graphos/api-keys/#graph-api-keys) that the router should use to authenticate with GraphOS when fetching its supergraph schema. + +**Required** when using [managed federation](/federation/managed-federation/overview/), except when using an [offline license](#--license) to run the router or when using `APOLLO_KEY`. + + | +
| + |
+ Standard Check Behavior + (Legacy reference reporting) + |
+
+ Enhanced Check Behavior + (Extended reference reporting) + |
+
|---|---|---|
| + +###### Enum value removal + + | +Removing any enum values is considered a breaking change if any operations use the enum. | +Removing enum values is only a breaking change if historical operations use the specific enum value(s) that were removed. | +
| + +###### Default argument changes for input object fields + + | ++ Changing or removing a default argument is generally considered a breaking change, but changing or removing default values for input object fields isn't. + | ++ Changing or removing default values for input object fields is considered a breaking change. + +You can [configure checks to ignore default values changes](/graphos/platform/schema-management/checks#ignored-conditions-settings). + + | +
| + +###### Nullable input object field removal + + | +Removing a nullable input object field is always considered a breaking change. | +Removing a nullable input object field is only considered a breaking change if the nullable field is present in historical operations. If the nullable field is always omitted in historical operations, its removal isn't considered a breaking change. | +
| + +###### Changing nullable input object fields to non-nullable + + | +Changing a nullable input object field to non-nullable is considered a breaking change. | +Changing a nullable input object field to non-nullable is only considered a breaking change if the field had a null value in historical operations. If the field was always a non-null value in historical operations, changing it to non-nullable isn't considered a breaking change. |
+
RouterService");
+ supergraphService("SupergraphService");
+ executionService("ExecutionService");
+ subgraphService[["SubgraphService(s)"]];
+ end;
+ subgraphs[[Subgraphs]];
+ client --"1. Sends request"--> routerService;
+ routerService <-."2. Can send requestdetails to coprocessor
and receive modifications".-> coprocessing; + routerService --"3"--> supergraphService; + supergraphService <-."4. Can send request
details to coprocessor
and receive modifications".-> coprocessing; + supergraphService --"5"--> executionService; + executionService <-."6. Can send request
details to coprocessor
and receive modifications".-> coprocessing; + executionService --"7"--> subgraphService; + subgraphService <-."8. Can send request
details to coprocessor
and receive modifications".-> coprocessing; + subgraphService -- "9"--> subgraphs; + + class client,subgraphs,coprocessing secondary; +``` + +This diagram shows request execution proceeding "down" from a client, through the router, to individual subgraphs. Execution then proceeds back "up" to the client in the reverse order. + +As shown in the diagram above, the `RouterService`, `SupergraphService`, `ExecutionService`, and `SubgraphService` steps of the [request-handling lifecycle](/graphos/routing/customization/rhai/#router-request-lifecycle) can send these POST requests (also called **coprocessor requests**). + +Each supported service can send its coprocessor requests at two different **stages**: + +- As execution proceeds "down" from the client to individual subgraphs + - Here, the coprocessor can inspect and modify details of requests before GraphQL operations are processed. + - The coprocessor can also instruct the router to [_terminate_ a client request](#terminating-a-client-request) immediately. +- As execution proceeds back "up" from subgraphs to the client + - Here, the coprocessor can inspect and modify details of the router's response to the client. + +At _every_ stage, the router waits for your coprocessor's response before it continues processing the corresponding request. Because of this, you should maximize responsiveness by configuring _only_ whichever coprocessor requests your customization requires. + +### Multiple requests with `SubgraphService` + +If your coprocessor hooks into your router's `SubgraphService`, the router sends a separate coprocessor request _for each subgraph request in its query plan._ In other words, if your router needs to query three separate subgraphs to fully resolve a client operation, it sends three separate coprocessor requests. Each coprocessor request includes the [name](#servicename) and [URL](#uri) of the subgraph being queried. + +## Setup + +First, make sure your router is [connected to a GraphOS Enterprise organization](/router/enterprise-features/#enabling-enterprise-features). + +You configure external coprocessing in your router's [YAML config file](/router/configuration/overview/#yaml-config-file), under the `coprocessor` key. + +### Typical configuration + +This example configuration sends commonly used request and response details to your coprocessor (see the comments below for explanations of each field): + +
defers some fields + Note over Router: Resolves non-deferred
fields + Router->>Client: Returns data for
non-deferred fields + Note over Router: Resolves deferred
fields + Router->>Client: Returns data for
deferred fields +``` + +For a single query with deferred fields, your router sends multiple "chunks" of response data to the client. If you enable coprocessor requests for the `RouterResponse` stage, your router sends a separate coprocessor request for _each chunk_ it returns as part of a deferred query. + +**Note the following about handling deferred response chunks:** + +- The [`status_code`](#status_code) and [`headers`](#headers) fields are included only in the coprocessor request for any response's _first_ chunk. These values can't change after the first chunk is returned to the client, so they're subsequently omitted. + +- If your coprocessor modifes the response [`body`](#body) for a response chunk, it must provide the new value as a _string_, _not_ as an object. This is because response chunk bodies include multipart boundary information in addition to the actual serialized JSON response data. [See examples.](#examples-of-deferred-response-chunks) + + - Many responses will not contain deferred streams and for these the body string can usually be fairly reliably transformed into a JSON object for easy manipulation within the coprocessor. Coprocessors should be carefully coded to allow for the presence of a body that is not a valid JSON object. + +- Because the data is a JSON string at both `RouterRequest` and `RouterResponse`, it's entirely possible for a coprocessor to rewrite the body from invalid JSON content into valid JSON content. This is one of the primary use cases for `RouterRequest` body processing. + +### Examples of deferred response chunks + +The examples below illustrate the differences between the _first_ chunk of a deferred response and all subsequent chunks: + +#### First response chunk + +The first response chunk includes `headers` and `statusCode` fields: + +```json +{ + "version": 1, + "stage": "RouterResponse", + "id": "8dee7fe947273640a5c2c7e1da90208c", + "sdl": "...", // String omitted due to length + // highlight-start + "headers": { + "content-type": ["multipart/mixed;boundary=\"graphql\";deferSpec=20220824"], + "vary": ["origin"] + }, + // highlight-end + "body": "\r\n--graphql\r\ncontent-type: application/json\r\n\r\n{\"data\":{\"me\":{\"id\":\"1\"}},\"hasNext\":true}\r\n--graphql\r\n", + "context": { + "entries": { + "apollo::supergraph::operation_kind": "query", + "apollo::telemetry::client_version": "", + "apollo::telemetry::client_name": "manual" + } + }, + "statusCode": 200 //highlight-line +} +``` + +#### Subsequent response chunk + +Subsequent response chunks omit the `headers` and `statusCode` fields: + +```json +{ + "version": 1, + "stage": "RouterResponse", + "id": "8dee7fe947273640a5c2c7e1da90208c", + "sdl": "...", // String omitted due to length + "body": "content-type: application/json\r\n\r\n{\"hasNext\":false,\"incremental\":[{\"data\":{\"name\":\"Ada Lovelace\"},\"path\":[\"me\"]}]}\r\n--graphql--\r\n", + "context": { + "entries": { + "apollo::supergraph::operation_kind": "query", + "apollo::telemetry::client_version": "", + "apollo::telemetry::client_name": "manual" + } + } +} +``` + +## Adding authorization claims via coprocessor + +To use the [authorization directives](/router/configuration/authorization#authorization-directives), a request needs to include **claims**—the details of its authentication and scope. The most straightforward way to add claims is with [JWT authentication](/router/configuration/./authn-jwt). You can also add claims with a [`RouterService` or `SupergraphService` coprocessor](#how-it-works) since they hook into the request lifecycle before the router applies authorization logic. + +An example configuration of the router calling a coprocessor for authorization claims: + +```yaml title="router.yaml" +coprocessor: + url: http://127.0.0.1:8081 # Required. Replace with the URL of your coprocessor's HTTP endpoint. + router: # By including this key, a coprocessor can hook into the `RouterService`. You can also use `SupergraphService` for authorization. + request: # By including this key, the `RouterService` sends a coprocessor request whenever it first receives a client request. + headers: false # These boolean properties indicate which request data to include in the coprocessor request. All are optional and false by default. + context: all # The authorization directives works with claims stored in the request's context +``` + +This configuration prompts the router to send an HTTP POST request to your coprocessor whenever it receives a client request. For example, your coprocessor may receive a request with this format: + +```json +{ + "version": 1, + "stage": "RouterRequest", + "control": "continue", + "id": "d0a8245df0efe8aa38a80dba1147fb2e", + "context": { + "entries": { + "accepts-json": true + } + } +} +``` + +When your coprocessor receives this request from the router, it should add claims to the request's [`context`](#context) and return them in the response to the router. Specifically, the coprocessor should add an entry with a claims object. The key must be `apollo::authentication::jwt_claims`, and the value should be the claims required by the authorization directives you intend to use. For example, if you want to use [`@requireScopes`](/router/configuration/authorization#requiresscopes), the response may look something like this: + +```json +{ + "version": 1, + "stage": "RouterRequest", + "control": "continue", + "id": "d0a8245df0efe8aa38a80dba1147fb2e", + "context": { + "entries": { + "accepts-json": true, + "apollo::authentication::jwt_claims": { + "scope": "profile:read profile:write" + } + } + } +} +``` + +## Additional resources + +- See the Apollo Solutions ["Hello World" coprocessor](https://github.com/apollosolutions/example-coprocessor-helloworld) for an example of a coprocessor that simply logs the router's payload. +- See the following Apollo Solutions authorization and authentication examples: + - [External authentication coprocessor example](https://github.com/apollosolutions/example-coprocessor-external-auth) + - [Custom auth coprocessor example](https://github.com/apollosolutions/example-coprocessor-custom-auth-directive) + - [`@policy` coprocessor example](https://github.com/apollosolutions/example-coprocessor-auth-policy) +- Use the Apollo Solutions [router extensibility load testing repository](https://github.com/apollosolutions/router-extensibility-load-testing) to load test coprocessors. + +
| Property / Type | +Description | +
|---|---|
| + +**Control properties** + + | +|
| + +##### `control` + +`string | object` + + | ++ +Indicates whether the router should continue processing the current client request. In coprocessor request bodies from the router, this value is always the string value `continue`. + +In your coprocessor's response, you can instead return an _object_ with the following format: + +```json +{ "break": 400 } +``` + +If you do this, the router terminates the request-handling lifecycle and immediately responds to the client with the provided HTTP code and response [`body`](#body) you specify. + +For details, see [Terminating a client request](#terminating-a-client-request). + + | +
| + +##### `id` + +`string` + + | ++ +A unique ID corresponding to the client request associated with this coprocessor request. + +**Do not return a _different_ value for this property.** If you do, the router treats the coprocessor request as if it failed. + + | +
| + +##### `subgraphRequestId` + +`string` + + | ++ +A unique ID corresponding to the subgraph request associated with this coprocessor request (only available at the `SubgraphRequest` and `SubgraphResponse` stages). + +**Do not return a _different_ value for this property.** If you do, the router treats the coprocessor request as if it failed. + + | +
| + +##### `stage` + +`string` + + | ++ +Indicates which stage of the router's [request-handling lifecycle](/graphos/routing/customization/rhai/#router-request-lifecycle) this coprocessor request corresponds to. + +This value is one of the following: + +- `RouterRequest`: The `RouterService` has just received a client request. +- `RouterResponse`: The `RouterService` is about to send response data to a client. +- `SupergraphRequest`: The `SupergraphService` is about to send a GraphQL request. +- `SupergraphResponse`: The `SupergraphService` has just received a GraphQL response. +- `SubgraphRequest`: The `SubgraphService` is about to send a request to a subgraph. +- `SubgraphResponse`: The `SubgraphService` has just received a subgraph response. + +**Do not return a _different_ value for this property.** If you do, the router treats the coprocessor request as if it failed. + + | +
| + +##### `version` + +`number` + + | ++ +Indicates which version of the coprocessor request protocol the router is using. + +Currently, this value is always `1`. + +**Do not return a _different_ value for this property.** If you do, the router treats the coprocessor request as if it failed. + + | +
| + +**Data properties** + + | +|
| + +##### `body` + +`string | object` + + | ++ +The body of the corresponding request or response. + +This field is populated when the underlying HTTP method is `POST`. If you are looking for operation data on `GET` requests, that info will be populated in the `path` parameter per the [GraphQL over HTTP spec](https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md#get). + +If your coprocessor [returns a _different_ value](#responding-to-coprocessor-requests) for `body`, the router replaces the existing body with that value. This is common when [terminating a client request](#terminating-a-client-request). + +This field's type depends on the coprocessor request's [`stage`](#stage): + +- For `SubgraphService` stages, `body` is a JSON _object_. +- For `SupergraphService` stages, `body` is a JSON _object_. +- For `RouterService` stages, `body` is a JSON _string_. + - This is necessary to support handling [deferred queries](#handling-deferred-query-responses). + - If you modify `body` during the `RouterRequest` stage, the new value must be a valid string serialization of a JSON object. If it isn't, the router detects that the body is malformed and returns an error to the client. + +This field's structure depends on whether the coprocessor request corresponds to a request, a standard response, or a response "chunk" for a deferred query: + +- **If a request,** `body` usually contains a `query` property containing the GraphQL query string. +- **If a standard response,** `body` usually contains `data` and/or `errors` properties for the GraphQL operation result. +- **If a response "chunk",** `body` contains `data` for _some_ of the operation fields. + +By default, the `RouterResponse` stage returns _redacted_ errors within the `errors` field. To process subgraph errors manually in your coprocessor, enable [subgraph error inclusion](/router/configuration/subgraph-error-inclusion). + + | +
| + +##### `context` + +`object` + + | ++ +An object representing the router's shared context for the corresponding client request. + +If your coprocessor [returns a _different_ value](#responding-to-coprocessor-requests) for `context`, the router replaces the existing context with that value. + + | +
| + +##### `hasNext` + +`bool` + + | ++ +When `stage` is `SupergraphResponse`, if present and `true` then there will be subsequent `SupergraphResponse` calls to the co-processor for each multi-part (`@defer`/subscriptions) response. + + | +
| + +##### `headers` + +`object` + + | ++ +An object mapping of all HTTP header names and values for the corresponding request or response. + +Ensure headers are handled like HTTP headers in general. For example, normalize header case before your coprocessor operates on them. + +If your coprocessor [returns a _different_ value](#responding-to-coprocessor-requests) for `headers`, the router replaces the existing headers with that value. + +> The router discards any `content-length` headers sent by coprocessors because incorrect `content-length` values can lead to HTTP request failures. + + | +
| + +##### `method` + +`string` + + | ++ +The HTTP method that is used by the request. + + | +
| + +##### `path` + +`string` + + | ++ +The `RouterService` or `SupergraphService` path that this coprocessor request pertains to. + + | +
| + +##### `sdl` + +`string` + + | ++ +A string representation of the router's current supergraph schema. + +This value can be very large, so you should avoid including it in coprocessor requests if possible. + +The router ignores modifications to this value. + + | +
| + +##### `serviceName` + +`string` + + | ++ +The name of the subgraph that this coprocessor request pertains to. + +This value is present only for coprocessor requests from the router's `SubgraphService`. + +**Do not return a _different_ value for this property.** If you do, the router treats the coprocessor request as if it failed. + + | +
| + +##### `statusCode` + +`number` + + | ++ +The HTTP status code returned with a response. + + | +
| + +##### `uri` + +`string` + + | ++ +When `stage` is `SubgraphRequest`, this is the full URI of the subgraph the router will query. + + | +
| + +##### `query_plan` + +`string` + + | ++ +When `stage` is `ExecutionRequest`, this contains the query plan for the client query. It cannot be modified by the coprocessor. + + | +
+
+That's it! You've successfully sent a query to a router running a development graph and received a response.
+
+
+## Next steps
+
+Now that you've run the router locally, explore more about deployment and configuration:
+
+- Deploy the router [in your own infrastructure](/graphos/routing/self-hosted) with containers and/or Helm.
+- [Configure runtime features](/router/configuration/overview) of the router.
diff --git a/docs/source/routing/graphos-features.mdx b/docs/source/routing/graphos-features.mdx
index 7162508059..0a54ac5bf0 100644
--- a/docs/source/routing/graphos-features.mdx
+++ b/docs/source/routing/graphos-features.mdx
@@ -1,16 +1,16 @@
---
-title: GraphOS Router Features
-subtitle: Use router features enabled by GraphOS plans
+title: Licensed GraphOS Router Features
+subtitle: Features that requiring a licensed GraphOS plan
description: Unlock Enterprise features for the GraphOS Router by connecting it to Apollo GraphOS.
redirectFrom:
- /router/enterprise-features
---
-A router connected to GraphOS, whether cloud-hosted or self-hosted, is called a **GraphOS Router**. It has access to specific GraphOS features depending on the connected GraphOS organization's plan. Refer to the [pricing page](https://www.apollographql.com/pricing#graphos-router) to compare GraphOS Router features across plan types.
+This page lists the additional features of GraphOS Router that are enabled via integration with a licensed GraphOS plan.
-## GraphOS Router features
+> Refer to the [pricing page](https://www.apollographql.com/pricing) to compare GraphOS Router features across plan types.
-The GraphOS Router supports a collection of premium features specific to GraphOS. These features include:
+## GraphOS Router licensed features
- Real-time updates via [GraphQL subscriptions](/graphos/routing/operations/subscriptions)
- Improved performance with [query batching](/graphos/routing/performance/query-batching)
@@ -25,163 +25,13 @@ The GraphOS Router supports a collection of premium features specific to GraphOS
- An [offline license](/graphos/reference/router/graphos-features#the-enterprise-license) that enables running the router with GraphOS features when disconnected from the internet.
- [Using contexts to share data](/graphos/schema-design/federated-schemas/entities/use-contexts) with the `@context` and `@fromContext` directives
-For details on these features, see [this blog post](https://blog.apollographql.com/apollo-router-v1-12-improved-router-security-performance-and-extensibility) in addition to the documentation links above.
+## Enabling licensed plan features
-### Enabling plan-specific features
-
-To enable support for plan-specific features in GraphOS Router:
+To enable licensed plan features in a router:
- You must run GraphOS Router v1.12 or later. [Download the latest version.](/graphos/reference/router/self-hosted-install#1-download-and-extract-the-router-binary)
- Certain features might require a later router version. See a particular feature's documentation for details.
- Your 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](/graphos/reference/router/configuration#environment-variables) when starting the router.
- - If your router _already_ connects to your GraphOS organization, no further action is required.
-
-### The GraphOS license
-
-Whenever your router instance starts up and connects to GraphOS, it fetches a **license**, which is the credential that authorizes its use of GraphOS features:
-
-```mermaid
-flowchart LR;
- subgraph "Your Infrastructure";
- router(["GraphOS Router"]);
- end;
- subgraph "GraphOS";
- uplink(Apollo Uplink)
- end;
- router--"Fetches supergraph schemaand license"-->uplink; -``` - -A router instance retains its license for the duration of its execution. If you stop 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](/graphos/routing/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. To learn more about multi-cloud Uplink, read the [Apollo blog post](https://www.apollographql.com/blog/announcement/backend/introducing-multi-cloud-support-for-apollo-uplink). - -A router instance's license is valid for the duration of your organization's current subscription billing period (plus a [grace period](#grace-period-for-expired-plans)), even if the router temporarily becomes disconnected from GraphOS. - -
and license"-->uplink; +``` + +A router instance's license is valid for the duration of your organization's current subscription billing period (plus a [grace period](#grace-period-for-expired-plans)), even if the router temporarily becomes disconnected from GraphOS. + +## Licenses with local development + +You might also need to run an GraphOS Router instance on your local machine, such as with the [`rover dev`](/graphos/graphs/local-development) command. It's likely that your local router instance doesn't connect to GraphOS to get its supergraph schema from Uplink. For example, you can run `rover dev` to perform composition locally. + +**You _can_ use GraphOS Router features with a locally composed supergraph schema!** To do so, your router must still connect to GraphOS to obtain its [license](#the-graphos-license). + +### Set up local development + +These steps work both for running the router executable directly (`./router`) and for running it via `rover dev`: + +1. [Create a new variant](/graphos/graphs/federated-graphs/#adding-a-variant-via-the-rover-cli) for your supergraph that you'll use _only_ to fetch GraphOS 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 + type Query { + hello: String + } + ``` + +2. Create a [graph API key](/graphos/platform/access-management/api-keys#graph-api-keys) 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 + APOLLO_GRAPH_REF="..." APOLLO_KEY="..." ./router --supergraph schema.graphql + ``` + + - The value of `APOLLO_GRAPH_REF` is the graph ref for the new, license-specific variant you created (for example, `docs-example-graph@local-licenses`). + - The value of `APOLLO_KEY` is the graph API key you created. + +4. Your router will fetch an GraphOS license while using its locally composed supergraph schema. + +
+
-API]; + serviceC[Posts
API]; + end + router -.->|"❌ Subquery"| serviceB & serviceC; + clients -->|"⚠️Unauthorized
request"| router; + ``` + + - If every field in a particular subquery requires authorization, the router's [query planner](/router/customizations/overview#request-path) can _eliminate entire subgraph requests_ for unauthorized requests. For example, a request may have permission to view a particular user's posts on a social media platform but not have permission to view any of that user's personally identifiable information (PII). Check out [How it works](/graphos/routing/security/authorization#how-it-works) to learn more. + + ```mermaid + flowchart LR; + clients(Client); + subgraph Router[" "] + router(["GraphOS Router"]); + serviceB[Users
API]; + serviceC[Posts
API]; + end + router -->|"✅ Authorized
subquery"| serviceC; + router -.->|"❌ Unauthorized
subquery"| serviceB; + clients -->|"⚠️ Partially authorized
request"| router; + ``` + + - Also, [query deduplication](/router/configuration/traffic-shaping/#query-deduplication) groups requested fields based on their required authorization. Entire groups can be eliminated from the query plan if they don't have the correct authorization. + +- **Declarative access rules**: You define access controls at the field level, and GraphOS [composes](/graphos/routing/security/authorization#composition-and-federation) them across your services. These rules create graph-native governance without the need for an extra orchestration layer. + +- **Principled architecture**: Through composition, the router centralizes authorization logic while allowing for auditing at the service level. This centralized authorization is an initial checkpoint that other service layers can reinforce. + + ```mermaid + flowchart LR; + clients(Client); + Level2:::padding + subgraph Level1["
🔐 Router layer "] + router(["GraphOS Router"]); + subgraph Level2["🔐 Service layer"] + serviceB[Users
API]; + serviceC[Posts
API]; + end + end + + router -->|"Subquery"| serviceB & serviceC; + clients -->|"Request"| router; + + classDef padding padding-left:1em, padding-right:1em + ``` + +
API]; - serviceC[Posts
API]; - end - router -.->|"❌ Subquery"| serviceB & serviceC; - clients -->|"⚠️Unauthorized
request"| router; - ``` - - - If every field in a particular subquery requires authorization, the router's [query planner](/router/customizations/overview#request-path) can _eliminate entire subgraph requests_ for unauthorized requests. For example, a request may have permission to view a particular user's posts on a social media platform but not have permission to view any of that user's personally identifiable information (PII). Check out [How it works](#how-it-works) to learn more. - - ```mermaid - flowchart LR; - clients(Client); - subgraph Router[" "] - router(["GraphOS Router"]); - serviceB[Users
API]; - serviceC[Posts
API]; - end - router -->|"✅ Authorized
subquery"| serviceC; - router -.->|"❌ Unauthorized
subquery"| serviceB; - clients -->|"⚠️ Partially authorized
request"| router; - ``` - - - Also, [query deduplication](/router/configuration/traffic-shaping/#query-deduplication) groups requested fields based on their required authorization. Entire groups can be eliminated from the query plan if they don't have the correct authorization. - -- **Declarative access rules**: You define access controls at the field level, and GraphOS [composes](#composition-and-federation) them across your services. These rules create graph-native governance without the need for an extra orchestration layer. - -- **Principled architecture**: Through composition, the router centralizes authorization logic while allowing for auditing at the service level. This centralized authorization is an initial checkpoint that other service layers can reinforce. - - ```mermaid - flowchart LR; - clients(Client); - Level2:::padding - subgraph Level1["
🔐 Router layer "] - router(["GraphOS Router"]); - subgraph Level2["🔐 Service layer"] - serviceB[Users
API]; - serviceC[Posts
API]; - end - end - - router -->|"Subquery"| serviceB & serviceC; - clients -->|"Request"| router; - - classDef padding padding-left:1em, padding-right:1em - ``` - -