Skip to main content
Version: v2.x

Allow-list of operations

Introduction

The Allow-list is a list of safe operations (GraphQL queries, mutations or subscriptions) that is stored by the GraphQL engine in its metadata. When enabled, it can be used to restrict the GraphQL engine so that it executes only those operations that are present in the list (available after version v1.0.0-beta.1).

Adding or removing a operation in allow-list

You can add or remove a operation in the allow-list in two ways:

  • Using the console: Head to the Settings (⚙) --> Allow list section in the console. You can add a new operation to the allow-list or upload a list of new operations from a file that will be added to the allow-list. You can also see a list of existing operations in the allow-list and delete them individually.

    • You can add an individual operation, like the one below, manually to the allow-list with a unique name. Note that this unique name is just an identifier for the query in the collection, it is not related to the operation name of the query.

      query ($id: Int!){
      user_by_pk(id: $id){
      __typename
      id
      name
      company
      }
      }
    • You can upload files, like this sample file, to add multiple operations to the allow-list (each operation needs to have a name).

  • Using metadata APIs: Queries can be stored in collections and a collection can be added to or removed from the allow-list. See Collections & Allow-list APIs for API reference.

Note
  • The allow list queries are validated against the schema. So, adding an invalid query will result in inconsistent metadata error.

  • __typename introspection fields will be ignored when adding operations and comparing them to the allow-list.

  • Any introspection queries that your client apps require will have to be explicitly added to the allow-list to allow running them.

  • The order of fields in a query will be strictly compared. E.g. assuming the query in the first example above is part of the allow-list, the following query will be rejected:

    query ($id: Int!){
    user_by_pk(id: $id){
    __typename
    name
    id
    company
    }
    }
  • The allow-list is stored in the metadata. To version control the state of the list, you are required to export the metadata. See Managing Hasura metadata for more details.

  • You can modify the allow-list without actually enabling it on your instance.

Role based allow-list

A role based allow-list is useful when you would like a query collection to be accessible to only certain roles.

Note

Role based allow-lists are supported in cloud/enterprise products, from version v2.3.0. In OSS, role based allow-lists entries are ignored.

On older versions (which do not support role based allow-lists), any role based allow-list metadata entry will get treated as global. Hence, caution is advised when using role based allow-list metadata with older versions.

Enable allow-list

The allow-list validation can be enabled by setting the HASURA_GRAPHQL_ENABLE_ALLOWLIST environment variable to true or running the GraphQL engine with the --enable-allowlist flag (default value is false). See reference docs.

Note

The allow-list validation will not be enforced for the admin role.

The following are the recommended best practices for enabling/disabling allow-list based validation:

  • In development instances: During development or in dev instances, disable allow-list (default setting) to allow complete access to the GraphQL schema. Add/remove operations in the allow-list and then export the metadata for version-control (so you can apply it to other instances).
  • In CI/CD instances: Enable the allow-list for testing.
  • In production instances: Enabling the allow-list is highly recommended when running the GraphQL engine in production.
Allow Lists in Hasura Cloud

Hasura Cloud lets you generate allowed queries from real usage in your application. For more, information, see Allow Lists in Hasura Cloud.