Skip to content

Commit 38a6c2c

Browse files
henriquessbhenriquessb
authored
Merge pull request #2146 from vtexdocs/EDU-15868
EDU-15868: GraphQL builder 2.x
2 parents 8d7c359 + 5588189 commit 38a6c2c

File tree

4 files changed

+184
-30
lines changed

4 files changed

+184
-30
lines changed

‎docs/guides/vtex-io/GraphQL/graphql-authorization-in-io-apps.mdx‎

Lines changed: 89 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,52 +4,120 @@ slug: "graphql-authorization-in-io-apps"
44
hidden: false
55
excerpt: "Learn to implement and use protected GraphQL operations with IO apps."
66
createdAt: "2025-06-30T14:00:00.000Z"
7-
updatedAt: "2025-06-30T14:00:00.000Z"
7+
updatedAt: "2025-09-30T11:00:00.000Z"
88
---
9-
Authenticated GraphQL requests are crucial for securing access to your VTEX IO app's data and functionalities. Authentication ensures that only authorized users or applications can interact with your GraphQL endpoints, protecting sensitive information and preventing unauthorized actions. Besides authentication, app developers can implement authorization to control who can access specific resources and what operations they can perform.
9+
Authenticated GraphQL requests are crucial for securing access to your VTEX IO app's data and functions. Authentication ensures that only authorized users or applications can interact with your GraphQL endpoints, protecting sensitive information and preventing unauthorized actions. In addition to authentication, app developers can implement authorization to control who can access specific resources and what operations they can perform.
1010

11-
GraphQL authorization in VTEX IO apps works with auth tokens and [directives](https://graphql.org/learn/schema/#directives) within your GraphQL schema, enabling fine-grained access control based on [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). The app identifies the requester by the [auth token](https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens) in [apps](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-a-vtex-app) or the [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) in API calls, which will have [roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) or [policies](https://developers.vtex.com/docs/guides/vtex-io-documentation-policies) associated with VTEX's resources.
11+
GraphQL authorization in VTEX IO apps works with auth tokens and [directives](https://graphql.org/learn/schema/#directives) within your GraphQL schema, enabling fine-grained access control based on [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). The app identifies the requester by the [auth token](https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens) in [apps](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-a-vtex-app) or the [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) in API calls. These tokens have [roles](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) or [policies](https://developers.vtex.com/docs/guides/vtex-io-documentation-policies) associated with VTEX resources.
1212

1313
In this guide, you will learn how to:
1414

15-
1. Implement protected operations with GraphQL APIs in apps using authorization.
16-
2. Make requests in apps with the proper authorization.
17-
3. Make external requests with the appropriate authorization.
15+
1. Implement protected GraphQL API operations in apps using authorization.
16+
2. Make authorized requests from apps.
17+
3. Make external requests with appropriate authorization.
18+
19+
> ℹ️ Only VTEX apps, Admin users, and [application keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) can be authorized to make GraphQL requests, as they must be associated with a role or policy that grants access to a License Manager resource. Store users don't have this type of access.
1820
19-
> ℹ️ Only VTEX apps, Admin users, and [application keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) can be authorized in GraphQL requests, since they must be associated with a role or policy granting access to a License Manager resource. Store users don't have this type of access.
2021
## Implementing GraphQL API authorization in apps
2122

22-
By default, GraphQL APIs in VTEX apps don't require authorization. To enable authorization, you must add the `@auth` directive to the specific fields or operations in your GraphQL schema that require protection. This directive ensures that only requesters with access to the corresponding [License Manager resource](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) are allowed to execute the operation.
23+
The `@auth` directive has different implementation methods depending on the builder version.
24+
25+
For the builder version `1.x`, the directive is optional. If a query or mutation doesn't have the directive, it's considered public by default. For the builder version `2.x`, the directive is mandatory.
26+
27+
To enable authorization, you must add the `@auth` directive to the specific fields or operations in your GraphQL schema that need protection. This directive ensures that only requesters with access to the corresponding [License Manager resource](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) are allowed to execute the operation.
2328

2429
The `@auth` directive uses the following arguments:
2530

26-
- `productCode`: The numeric code that identifies the product in License Manager (for example, `"66"` for **VTEX IO**).
27-
- `resourceCode`: The License Manager resource identifier (for example, `"workspace-read-write"` for **Workspace CRUD**).
31+
<table>
32+
<thead>
33+
<tr>
34+
<th>Argument</th>
35+
<th>Description</th>
36+
<th><a href="https://developers.vtex.com/docs/guides/vtex-io-documentation-graphql-builder#versioning" target="_blank">Builder version</a> details</th>
37+
</tr>
38+
</thead>
39+
<tbody>
40+
<tr>
41+
<td><code>scope</code></td>
42+
<td>
43+
The authorization scope of the query or mutation. It has two possible values:
44+
<ul>
45+
<li><code>PUBLIC</code>: The query is public, so it doesn't require any authorization. This scope is mostly used for shoppers browsing a store.</li>
46+
<li><code>PRIVATE</code>: The query is private, which requires authorization for a specific License Manager resource and product. This scope should be used for scenarios other than store browsing by a shopper, such as in the Admin.</li>
47+
</ul>
48+
</td>
49+
<td>Works only on version <code>2.x</code>, and is mandatory.</td>
50+
</tr>
51+
<tr>
52+
<td><code>productCode</code></td>
53+
<td>The numeric code that identifies the product in License Manager (for example, <code>"66"</code> for <b>VTEX IO</b>). See the product codes in the <b>Product ID</b> column of the table in <a href="https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3" target="_blank">License Manager resources</a>.</td>
54+
<td>Works on versions <code>1.x</code> and <code>2.x</code>. For <code>2.x</code>, this argument is mandatory if scope is set to <code>PRIVATE</code>.</td>
55+
</tr>
56+
<tr>
57+
<td><code>resourceCode</code></td>
58+
<td>The License Manager resource identifier (for example, <code>"workspace-read-write"</code> for <b>Workspace CRUD</b>). See the resource codes in the <b>Key</b> column of the table in <a href="https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3" target="_blank">License Manager resources</a>.</td>
59+
<td>Works on versions <code>1.x</code> and <code>2.x</code>. For <code>2.x</code>, this argument is mandatory if scope is set to <code>PRIVATE</code>.</td>
60+
</tr>
61+
</tbody>
62+
</table>
63+
64+
Examples:
65+
66+
With version `1.x`:
67+
68+
```graphql
69+
type Mutation {
70+
createWorkspace(account: String, workspace: String): GenericResponse
71+
@auth(productCode: "66", resourceCode: "workspace-read-write")
72+
}
73+
```
2874

29-
Example:
75+
Public with version `2.x`:
3076

31-
```graphql graphql/schema.graphql mark=2
32-
createWorkspace(account: String, workspace: String): GenericResponse
33-
@auth(productCode: "66", resourceCode: "workspace-read-write")
77+
```graphql
78+
type Query {
79+
source(id: ID!): String
80+
@auth(scope: PUBLIC)
81+
}
3482
```
3583

36-
In this example, when the user requests the `createWorkspace` mutation, VTEX will check if this user has access to the `workspace-read-write` resource from License Manager. If the user has this access, the endpoint will process as intended. Otherwise, the request will be denied.
84+
In this example, there is no verification of whether the requester has access to a specific License Manager resource.
85+
86+
Private with version `2.x`:
87+
88+
```graphql
89+
type Mutation {
90+
createWorkspace(account: String, workspace: String): GenericResponse
91+
@auth(scope: PRIVATE, productCode: "66", resourceCode: "workspace-read-write")
92+
}
93+
```
94+
95+
In this example, when the user requests the `createWorkspace` mutation, VTEX checks if the user has access to the `workspace-read-write` resource from License Manager. If the user has this access, the endpoint will be processed as intended. Otherwise, the request will be denied.
3796

3897
You can see the available products and resources in [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).
3998

99+
### Error scenarios
100+
101+
If a developer tries to build an app with the GraphQL builder `2.x`, the [VTEX IO CLI](https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference) will show an error message in the following cases:
102+
103+
- Any query or mutation lacks the `@auth` directive.
104+
- The `scope` argument is missing in the directive.
105+
- When `scope` is `PRIVATE` in the directive and the `productCode` or `resourceCode` arguments are missing.
106+
107+
![GraphQL auth directive error](../../images/graphql-auth-directive-error.png)
108+
40109
## Making requests to protected GraphQL APIs from a VTEX IO app
41110

42-
When making requests to a protected GraphQL API from another VTEX IO app, you must export a [custom Client](https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients) that extends the `AppGraphQLClient` type and declare the auth token in the [Client](https://developers.vtex.com/docs/guides/vtex-io-documentation-clients)'s `VtexIdClientAutCookie` header. The requester must have the role or policy that includes the `resourceCode` and `productCode` defined in the target operation's `@auth` directive.
111+
When making requests to a protected GraphQL API from another VTEX IO app, you must export a [custom Client](https://developers.vtex.com/docs/guides/vtex-io-documentation-how-to-create-and-use-clients) that extends the `AppGraphQLClient` type and set the `VtexIdclientAutCookie` header with the auth token in the [Client](https://developers.vtex.com/docs/guides/vtex-io-documentation-clients). The requester must have the role or policy that includes the `resourceCode` and `productCode` defined in the target operation's `@auth` directive.
43112

44-
Declare the token considering the requester context:
113+
Declare the token based on the requester's context:
45114

46115
- **App**: `ctx.authToken`.
47116
- **Admin user**: `ctx.adminUserAuthToken`.
48117

49118
Example
50119

51120
```typescript node/clients/catalogGraphQL/index.ts mark=9
52-
53121
import { AppGraphQLClient, InstanceOptions, IOContext } from '@vtex/api'
54122
export class CatalogGQL extends AppGraphQLClient {
55123
constructor(ctx: IOContext, options?: InstanceOptions) {
@@ -68,17 +136,17 @@ For details about token types, see [App authentication using auth tokens](https:
68136

69137
> ⚠️ Use the user token (Admin) whenever possible to properly identify the requester. The app token (`ctx.authToken`) should only be used when the user can't access the requested service.
70138
71-
## Making requests to protected GraphQL API apps
139+
## Making requests to protected GraphQL APIs of apps
72140

73-
When making external requests to a GraphQL API app, declare the [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) in the `VtexIdClientAutCookie` HTTP header. The requester must have a role that includes the resource and product defined in the endpoint's `@auth` directive.
141+
When making external requests to a GraphQL API of an app, include the [user token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens) in the `VtexIdclientAutCookie` HTTP header. The requester must have a role that includes the resource and product defined in the endpoint's `@auth` directive.
74142

75143
Example (cURL):
76144

77145
```sh terminal mark=4
78146
curl -X POST \
79147
'https://https://app.io.vtex.com/vtex.rewriter/v1/{account}/_v/graphql' \
80148
-H 'Content-Type: application/json' \
81-
-H 'VtexIdClientAutCookie: {your_user_token}' \
149+
-H 'VtexIdclientAutCookie: {your_user_token}' \
82150
-d '{
83151
"query": "
84152
mutation SaveInternal($route: InternalInput!) {

‎docs/guides/vtex-io/Reference/concepts/vtex-io-documentation-builders/vtex-io-documentation-graphql-builder.md‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,32 @@ slug: "vtex-io-documentation-graphql-builder"
44
excerpt: "Learn how to use the GraphQL builder."
55
hidden: false
66
createdAt: "2025-05-05T12:00:00.000Z"
7-
updatedAt: "2025-05-05T12:00:00.000Z"
7+
updatedAt: "2025-09-30T11:00:00.000Z"
88
category: "App Development"
99
---
1010

11-
The `graphql` builder handles the GraphQL app [schema](https://graphql.org/learn/schema/) and serves as an interface between frontend applications and backend [services](https://developers.vtex.com/docs/guides/vtex-io-documentation-service). This guide provides a comprehensive overview of how to use this builder effectively. For more information, check [Using GraphQL to retrieve data from Master Data](https://developers.vtex.com/docs/guides/services-6-graphql-retrieving-data-from-master-data) and the [official GraphQL documentation](https://graphql.com/learn/what-is-graphql/).
11+
The `graphql` builder handles the GraphQL app [schema](https://graphql.org/learn/schema/) and serves as an interface between frontend applications and backend [services](https://developers.vtex.com/docs/guides/vtex-io-documentation-service). This guide provides a comprehensive overview of how to use this builder effectively. For more information, see [Developing a GraphQL API in service apps](https://developers.vtex.com/docs/guides/developing-a-graphql-api-in-service-apps) and the [official GraphQL documentation](https://graphql.com/learn/what-is-graphql/).
1212

1313
> ℹ️ The `graphql` builder is used only when developing an app's GraphQL API. You don't need this builder to consume GraphQL APIs in IO apps.
1414
15+
## Versioning
16+
17+
The `graphql` builder is available in the following versions:
18+
19+
| Builder version | Mandatory `@auth` directive\* | Status |
20+
| :- | :- | :- |
21+
| `1.x` | No | Unavailable for new apps and new major versions of existing apps. Available for linking apps and publishing new minor and patch [versions](https://developers.vtex.com/docs/guides/vtex-io-documentation-releasing-a-new-app-version#understanding-app-versioning) of existing apps until January 7, 2026. |
22+
| `2.x` | Yes | Active |
23+
24+
\* The `@auth` directive adds an authorization step to GraphQL queries and mutations. For more details, see [GraphQL authorization in IO apps](https://developers.vtex.com/docs/guides/graphql-authorization-in-io-apps).
25+
26+
> ⚠️ Apps using deprecated builder versions can still run on the VTEX platform, but developers can't build or create new app versions using these builder versions.
27+
1528
## Folder structure
1629

17-
The `graphql` builder uses a `graphql` folder in the app’s root folder. This folder contains `.graphql` files with the schema definitions. Developers can structure the whole schema in a single file or split it into multiple files and subfolders.
30+
The `graphql` builder uses a `graphql` folder in the app's root folder. This folder contains `.graphql` files with the schema definitions. Developers can structure the whole schema in a single file or split it into multiple files and subfolders.
1831

19-
Our recommendation is to:
32+
We recommend you to:
2033

2134
- Define only the endpoints ([queries](https://graphql.org/learn/queries/), [mutations](https://graphql.org/learn/mutations/), and [subscriptions](https://graphql.org/learn/subscriptions/)) in `schema.graphql`.
2235
- Handle [directives](https://graphql.org/learn/schema/#directives) separately in `directives.graphql`.
@@ -35,13 +48,15 @@ graphql
3548

3649
To develop an app using the `graphql` builder, follow the steps below:
3750

38-
1. **Start with a template:** Download an app template such as [`graphql-example`](https://github.com/vtex-apps/graphql-example) or create a new project using the [`vtex init CLI command`](https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-usage#starting-a-new-project) and choose the `graphql-example` option.
39-
2. **Add the schema files**: Add the `.graphql` files with the schema definitions, including the endpoints (queries, mutations, and subscriptions), directives, and other types you want to define.
40-
3. **Add the API implementation logic**: Add the code that implements and instantiates the resolver functions. There's an example available in [Using GraphQL to retrieve data from Master Data](https://developers.vtex.com/docs/guides/services-6-graphql-retrieving-data-from-master-data).
41-
1. **Create the resolvers**: Create the resolver functions that will run when your GraphQL endpoints are called. The functions must have the same names as the endpoints defined in the schema. If you're developing a Node service, you should add the TypeScript code (`.ts` files) in the `node/resolvers` folder.
42-
2. **Instantiate the resolvers**: Add the code to instantiate the resolvers. If you're developing a Node service, in the `Service` class of the `node/index.ts` file, you should add a `graphql` field with the resolvers for each endpoint implemented along with the directives.
51+
1. **Start with a template:** Download an app template such as [`graphql-example`](https://github.com/vtex-apps/graphql-example) or create a new project using the [`vtex init` CLI command](https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-usage#starting-a-new-project) and select the `graphql-example` option.
52+
2. **Add the schema files:** Add the `.graphql` files with the schema definitions, including the endpoints (queries, mutations, and subscriptions), directives, and other custom types.
53+
3. **Add the API implementation logic**: Add the code that implements and instantiates the resolver functions.
54+
1. **Create the resolvers**: Create the resolver functions that will run when your GraphQL endpoints are called. The functions must have the same names as the endpoints defined in the schema. If you're developing a Node service, add the TypeScript code (`.ts` files) in the `node/resolvers` folder.
55+
2. **Instantiate the resolvers**: Add the code to instantiate the resolvers. If you're developing a Node service, in the `node/index.ts` file, within the `Service` class, you should add a `graphql` field that includes the resolvers for each implemented endpoint and the directives.
4356
4. **Testing**: [Link the app](https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app) to a development workspace for testing. Test the endpoints with the [GraphQL IDE](https://developers.vtex.com/docs/guides/graphql-ide).
4457

58+
For a more detailed tutorial on implementing an app with this builder, see [Developing a GraphQL API in service apps](https://developers.vtex.com/docs/guides/developing-a-graphql-api-in-service-apps).
59+
4560
## Use case examples
4661

4762
Below are some app examples that use the `graphql` builder:

0 commit comments

Comments
 (0)