Documentation
Feedback
Guides
App Development

App Development
GraphQL in VTEX IO
GraphQL authorization in IO apps

Learn to implement and use protected GraphQL operations with IO apps.

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.

Implementing GraphQL API authorization in apps

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:

graphql/schema.graphql

_10
createWorkspace(account: String, workspace: String): GenericResponse
_10
@auth(productCode: "66", resourceCode: "workspace-read-write")

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.

Making requests to protected GraphQL APIs from a VTEX IO app

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

node/clients/catalogGraphQL/index.ts

_13
_13
import { AppGraphQLClient, InstanceOptions, IOContext } from '@vtex/api'
_13
export class CatalogGQL extends AppGraphQLClient {
_13
constructor(ctx: IOContext, options?: InstanceOptions) {
_13
super('vtex.catalog-graphql@1.x', ctx, {
_13
...options,
_13
headers: {
_13
...options?.headers,
_13
VtexIdclientAutCookie: ctx.adminUserAuthToken,
_13
},
_13
})
_13
}
_13
}

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.

Making requests to protected GraphQL API apps

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):

terminal

_32
curl -X POST \
_32
'https://https://app.io.vtex.com/vtex.rewriter/v1/{account}/_v/graphql' \
_32
-H 'Content-Type: application/json' \
_32
-H 'VtexIdClientAutCookie: {your_user_token}' \
_32
-d '{
_32
"query": "
_32
mutation SaveInternal($route: InternalInput!) {
_32
internal {
_32
save(route: $route) {
_32
from
_32
id
_32
type
_32
binding
_32
resolveAs
_32
origin
_32
}
_32
}
_32
}
_32
",
_32
"variables": {
_32
"route": {
_32
"from": "/old-path",
_32
"declarer": "vtex.store@2.x",
_32
"type": "redirect",
_32
"id": "custom-redirect-old-path",
_32
"binding": "your-binding-id",
_32
"resolveAs": "/new-path",
_32
"origin": "internal",
_32
"disableSitemapEntry": false
_32
}
_32
}
_32
}'

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.

Contributors
1
Photo of the contributor
Was this helpful?
Yes
No
Suggest Edits (GitHub)
Contributors
1
Photo of the contributor
On this page