Allow-list for queries

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

Adding or removing a query in allow-list

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

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

    • You can add an individual query, like the one below, manually to the allow-list with a unique name.

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

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

Note

  • __typename introspection fields will be ignored when adding queries 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 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
       }
    }
    
  • 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.

Enable allow-list

The allow-list validation can be enabled by setting the HASURA_GRAPHQL_ENABLE_ALLOWLIST environment variable to true or running 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.