Documentation
Plugins
Trusted Documents

Trusted Documents

This plugin allows you to define a list of trusted GraphQL documents that can be executed by the gateway (also called Persisted Operations).

For additional information, please refer to Trusted Documents.

Configuration

Examples

This example is using a local file called trusted_documents.json as a store, using the Key->Value map format. The protocol exposed is based on HTTP POST, using the documentId parameter from the request body.

YAML

config:
  protocols:
    - field_name: "documentId"
      type: "document_id"
  store:
    format: "json_key_value"
    path: "trusted_documents.json"
    source: "file"
enabled: true
type: "trusted_documents"

JSON

{
  "config": {
    "protocols": [
      {
        "field_name": "documentId",
        "type": "document_id"
      }
    ],
    "store": {
      "format": "json_key_value",
      "path": "trusted_documents.json",
      "source": "file"
    }
  },
  "enabled": true,
  "type": "trusted_documents"
}

Reference

store
required

The store defines the source of trusted documents. The store contents is a list of hashes and GraphQL documents that are allowed to be executed.

The following options are valid for this field:
file

File-based store configuration. The path specified is relative to the location of the root configuration file. The file contents are loaded into memory on startup. The file is not reloaded automatically. The file format is specified by the format field, based on the structure of your file.

source
literal: file
required

To use this variation, please specify the type: file in your configuration.

path
string
required

A path to a local file on the file-system. Relative to the location of the root configuration file.

format
required

The format and the expected structure of the loaded store file.

The following options are valid for this field:
apollo_persisted_query_manifest

JSON file formated based on Apollo Persisted Query Manifest.

json_key_value

A simple JSON map of key-value pairs.

Example: {"key1": "query { __typename }"}

protocols
array
required

A list of protocols to be exposed by this plugin. Each protocol defines how to obtain the document ID from the incoming request. You can specify multiple kinds of protocols, if needed.

The following options are valid for this field:
apollo_manifest_extensions

This protocol is based on Apollo’s Persisted Query Extensions. The GraphQL operation key is sent over POST and contains extensions field with the GraphQL document hash.

Example: POST /graphql {"extensions": {"persistedQuery": {"version": 1, "sha256Hash": "123"}}

type
literal: apollo_manifest_extensions
required

To use this variation, please specify the type: apollo_manifest_extensions in your configuration.

document_id

This protocol is based on a POST request with a JSON body containing a field with the document ID. By default, the field name is documentId.

Example: POST /graphql {"documentId": "123", "variables": {"code": "AF"}, "operationName": "test"}

type
literal: document_id
required

To use this variation, please specify the type: document_id in your configuration.

field_name
string
default: "documentId"

The name of the JSON field containing the document ID in the incoming request.

http_get

This protocol is based on a HTTP GET request. You can customize where to fetch each one of the parameters from. Each request parameter can be obtained from a different source: query, path, or header. By defualt, all parameters are obtained from the query string.

Unlike other protocols, this protocol does not support sending GraphQL mutations.

Example: GET /graphql?documentId=123&variables=%7B%22code%22%3A%22AF%22%7D&operationName=test

type
literal: http_get
required

To use this variation, please specify the type: http_get in your configuration.

document_id_from
default: { "name": "documentId", "source": "search_query" }

Instructions for fetching the document ID parameter from the incoming HTTP request.

The following options are valid for this field:
search_query

Instructs the plugin to extract this parameter from the query string of the HTTP request.

source
literal: search_query
required

To use this variation, please specify the type: search_query in your configuration.

name
string
required

The name of the HTTP query parameter.

path

Instructs the plugin to extract this parameter from the path of the HTTP request.

source
literal: path
required

To use this variation, please specify the type: path in your configuration.

position
integer
required

The numeric value specific the location of the argument (starting from 0).

header

Instructs the plugin to extract this parameter from a header in the HTTP request.

source
literal: header
required

To use this variation, please specify the type: header in your configuration.

name
string
required

The name of the HTTP header.

variables_from
default: { "name": "variables", "source": "search_query" }

Instructions for fetching the variables parameter from the incoming HTTP request. GraphQL variables must be passed as a JSON-encoded string.

The following options are valid for this field:
search_query

Instructs the plugin to extract this parameter from the query string of the HTTP request.

source
literal: search_query
required

To use this variation, please specify the type: search_query in your configuration.

name
string
required

The name of the HTTP query parameter.

path

Instructs the plugin to extract this parameter from the path of the HTTP request.

source
literal: path
required

To use this variation, please specify the type: path in your configuration.

position
integer
required

The numeric value specific the location of the argument (starting from 0).

header

Instructs the plugin to extract this parameter from a header in the HTTP request.

source
literal: header
required

To use this variation, please specify the type: header in your configuration.

name
string
required

The name of the HTTP header.

operation_name_from
default: { "name": "operationName", "source": "search_query" }

Instructions for fetching the operationName parameter from the incoming HTTP request.

The following options are valid for this field:
search_query

Instructs the plugin to extract this parameter from the query string of the HTTP request.

source
literal: search_query
required

To use this variation, please specify the type: search_query in your configuration.

name
string
required

The name of the HTTP query parameter.

path

Instructs the plugin to extract this parameter from the path of the HTTP request.

source
literal: path
required

To use this variation, please specify the type: path in your configuration.

position
integer
required

The numeric value specific the location of the argument (starting from 0).

header

Instructs the plugin to extract this parameter from a header in the HTTP request.

source
literal: header
required

To use this variation, please specify the type: header in your configuration.

name
string
required

The name of the HTTP header.

allow_untrusted
boolean
optional

By default, this plugin does not allow untrusted operations to be executed. This is a security measure to prevent accidental exposure of operations that are not persisted.

Disable IntrospectionHTTP GET