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.

Enable Allow List

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

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

Open Allow List manager

Head to the API tab and find the Allow List section in the console.

AllowList manager

Adding or removing an operation in Allow List

Head to the API tab and find the Allow List section in the console.

  • Write operation: You can add an individual operation, like the one below, manually to the Allow List. These operations require unique names. This unique name is used 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
}
}

After writing your query or selecting a query from quick add dropdown menu, click Add Operation.

Add operation
  • Upload File: Alternatively, you can upload files, like this sample file, to add multiple operations to the Allow List. Each operation in the file will need a unique name. Once you've selected your file, click Add Operation.
Upload operation
Note
  • Allow List queries are validated against the schema. Adding an invalid query will result in an 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 must 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 Hasura's 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

Available on: Cloud

A role-based Allow List is useful when you would like a query collection(s) to be accessible to only certain roles.

Note

Server support for Role-based Allow Lists in Cloud/Enterprise products is available from version v2.3 and console support is available from version v2.13. In OSS, role-based entries are ignored.

On older versions (which do not support role-based Allow Lists), any role-based Allow List Metadata entry will be treated as global. Hence, caution is advised when using role-based Allow List Metadata with older versions.

Head to the API tab and find the Allow List section on the Console. On the left side bar, you can see a list of query collections. After selecting a query collection, you can enable the roles which should have access to any query collection via the Permissions tab.

Role based allow list

Quick-create allowed operations

Available on: Cloud

Hasura Cloud

This feature lets you add to the Allow List with one click from the record of past operations. (With Hasura GraphQL Engine CE, Allow Lists must be managed manually).

Hasura Cloud Console create new allowed operation

The following are the recommended best practices for enabling/disabling Allow-List-based validation:

  • In development instances: During development or in dev instances, disable the Allow List (default setting) to enable 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.