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.

GraphQL authorization in VTEX IO apps works with auth tokens and directives within your GraphQL schema, enabling fine-grained access control based on License Manager resources. The app identifies the requester by the auth token in apps or the user token in API calls, which will have roles or policies associated with VTEX's resources.

In this guide, you will learn how to:

1. Implement protected operations with GraphQL APIs in apps using authorization.
2. Make requests in apps with the proper authorization.
3. Make external requests with the appropriate authorization.

Only VTEX apps, Admin users, and application 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.

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 are allowed to execute the operation.

The @auth directive uses the following arguments:

• productCode: The numeric code that identifies the product in License Manager (for example, "66" for VTEX IO).
• resourceCode: The License Manager resource identifier (for example, "workspace-read-write" for Workspace CRUD).

Example:

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.

You can see the available products and resources in License Manager resources.

When making requests to a protected GraphQL API from another VTEX IO app, you must export a custom Client that extends the AppGraphQLClient type and declare the auth token in the Client'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.

Declare the token considering the requester context:

• App: ctx.authToken.
• Admin user: ctx.adminUserAuthToken.

Example

For details about token types, see App authentication using auth tokens.

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.

When making external requests to a GraphQL API app, declare the user token in the VtexIdClientAutCookie HTTP header. The requester must have a role that includes the resource and product defined in the endpoint's @auth directive.

Example (cURL):

You can make GraphQL requests with GraphQL IDEs that support custom HTTP headers, such as the one in the VTEX Admin. Not all GraphQL IDEs allow setting authentication headers, which may prevent requests to protected operations from being executed successfully.