We are releasing GraphQL builder 2.x for VTEX IO apps. Version 1.x will be deprecated. The GraphQL builder handles GraphQL schemas, used in API implementations for service apps.

Version 2.x requires all queries to use the @auth directive, enhancing security for apps using GraphQL APIs.

The @auth directive is added to queries and mutations to determine the authorization required for users or apps.

In GraphQL builder 1.x, the @auth directive is optional and defines a License Manager resource and product. Users or apps need a role or policy that includes the resource or product defined by the directive. Without the @auth directive, the query is public by default.

GraphQL builder 1.x will be deprecated on January 7, 2026. Existing apps built with version 1.x will continue to work, but you won't be able to create new apps or major versions of existing apps using version 1.x. After the deprecation date, apps using builder 1.x will fail to build via link or publish.

With builder version 2.x, the @auth directive is mandatory and requires the scope argument, which accepts the following values:

• PUBLIC: The query is public and doesn't require authorization.
• PRIVATE: The query is private and requires authorization for a specific License Manager resource and product. When using PRIVATE, the productCode and resourceCode arguments are also mandatory.

If an app is built with GraphQL builder version 2.x and is missing the @auth directive, the VTEX IO CLI will display an error message in these cases:

• Any query or mutation lacks the @auth directive.
• The scope argument is missing.
• The scope is PRIVATE, and productCode or resourceCode arguments are missing.

An error occurred while loading the image ../../images/graphql-auth-directive-error.png

This change enhances the security and transparency of GraphQL APIs in VTEX IO apps. Developers must now explicitly declare whether queries and mutations are public or require authorization within the schema.

To use the new builder version, developers must update their apps:

1. Update the GraphQL builder version to 2.x in the app's manifest.

   
   

   _10

   "builders": {

   _10

   "graphql": "2.x",

   _10

   ...

   _10

   },

   
   

2. Add the @auth directive to every query and mutation in the app's GraphQL schema, and include the scope argument. For public queries, use:

   
   

   _10

   type Query {

   _10

   source(id: ID!): String

   _10

   @auth(scope: PUBLIC)

   _10

   }

   
   

   For private queries, include the authorization requirements:

   
   

   _10

   type Query {

   _10

   book(id: ID!): Book

   _10

   @auth(scope: PRIVATE, productCode: "64", resourceCode: "read_account_config")

   _10

   }

   
   

For more information, see GraphQL builder and GraphQL authorization in IO apps.