Doc reviewed by localization #2320
Merged
+10
−10
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Navigation Preview LinkNo changes detected in the navigation.json file |
Contributor
Preview LinksOpen this URL to set up the portal with this branch changes. You can now access the edited pages with the following URLs:
|
Contributor
Documentation feedback for docs/localization/accessing-external-resources-within-a-vtex-io-app.mdxGeneral FeedbackThe explanation provides a good overview of how VTEX IO apps can access external resources using policies. It covers different types of policies and provides examples for each. However, there are some areas where the content can be improved to better adhere to the explanation guidelines, particularly regarding context, cross-references, and tone. Actionable Feedback
Suggested Revision---
title: "Accessing external resources within a VTEX IO app"
slug: "accessing-external-resources-within-a-vtex-io-app"
excerpt: "Learn how apps gain access to external resources with policies."
hidden: false
createdAt: "2025-11-04T12:00:00.000Z"
updatedAt: "2025-11-04T12:00:00.000Z"
---
Apps often need to interact with systems and data outside of their own environment to deliver comprehensive functionality. For example, an app might need to access a payment provider, integrate with an external CRM, or retrieve data from another VTEX IO app. To accomplish this, apps must declare policies to gain access to these external resources. An external resource could be:
- An endpoint from another VTEX IO app (REST or GraphQL)
- A VTEX API
- An endpoint external to VTEX (e.g., a payment provider, an external marketplace, etc.)
To have access, apps must declare policies in the `policies` list of the [`manifest.json` file](https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest).
The following sections describe the types of policies an app can have to access external resources.
## When to declare policies
Apps need to declare policies to gain access to external resources, which include:
- Access to specific content (file, image, etc.)
- Access to VTEX APIs
- Access to resources exposed through role-based policies
> ℹ️ Declaring policies is not required for resources exposed through [resource-based policies](https://developers.vtex.com/docs/guides/vtex-io-documentation-resource-policies), since these policies already define which apps are allowed.
### Policies from License Manager
These policies have predefined names and are related to native VTEX resources. To declare a policy of this type in the manifest, use the policy name in the `"name”` field. See the example below:
```json manifest.json mark=3:5
{
"policies": [
{
"name": "Sku.aspx"
}
]
}
```
You can find all available policy names in the **Key** column of the [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) table. For more details, see the [Policies from License Manager](https://developers.vtex.com/docs/guides/vtex-io-documentation-policies-from-license-manager) article.
### Policies from VTEX IO apps (role-based)
These policies grant access to app routes exposed with [role-based policies](?tab=t.0#heading=h.a8px17wrz58r). This policy type is used to access [GraphQL queries exposed by IO apps](https://developers.vtex.com/docs/guides/developing-a-graphql-api-in-service-apps). To declare a policy of this type in the manifest, use the format `{vendor}.{app-name}:{policy-name}` in the `"name"` field. See the example below:
```json manifest.json mark=3:5
{
"policies": [
{
"name": "vtex.messages:graphql-translate-messages"
}
]
}
```
To find out the names of the policies available in an app, you can see the app documentation or the `policies.json` file. Example: [Policies in the search-graph app](https://github.com/vtex-apps/search-graphql/blob/master/policies.json).
### Outbound-access policies
These policies should be used when none of the other types apply, with an explicit URL to the resource. Outbound-access policies are used to access resources external to VTEX.
To declare a policy of this type, use an object with the following structure:
- `"name"`: `"outbound-access"`.
- `"attrs"`: An object with two fields.
- `"host"`: String with the first part of the URL, usually containing the host or domain name.
- `"path"`: String with the last part of the URL, usually containing the path inside the domain name.
> ℹ️ `"host"` and `"path"` accept `{{account}}` as a variable and the `*` character as a wildcard.
Consider an app that needs access to the following resources:
- A VTEX API from the URL `{{account}}.vtexcommercestable.com.br/api/catalog_system/*`.
- The store's sitemap from the URL `{{account}}.vtexcommercestable.com.br/sitemap.xml`.
- An external resource from the URL `api.crowdin.com/api/project/*`.
For the app to gain access to these resources, declare the outbound-access policies as in the example below:
```json manifest.json mark=3:23
{
"policies": [
{
"name": "outbound-access",
"attrs": {
"host": "{{account}}.vtexcommercestable.com.br",
"path": "/api/catalog_system/*"
}
},
{
"name": "outbound-access",
"attrs": {
"host": "{{account}}.vtexcommercestable.com.br",
"path": "/sitemap.xml"
}
},
{
"name": "outbound-access",
"attrs": {
"host": "api.crowdin.com",
"path": "/api/project/*"
}
}
]
}
```Was this feedback useful?
|
Contributor
Documentation feedback for docs/localization/controlling-access-to-app-resources.mdxGeneral FeedbackThe Explanation documentation provides a comprehensive overview of controlling access to app resources in VTEX IO using role-based and resource-based policies. The content is well-structured with clear headings and a table summarizing the key differences between the two policy types. It also includes relevant links to other VTEX documentation. However, there are some areas where the documentation can be improved to better adhere to the Explanation guidelines. Actionable Feedback
Suggested Revision---
title: "Controlling access to app resources"
slug: "controlling-access-to-app-resources"
excerpt: "Learn how apps control access to their resources with policies."
hidden: false
createdAt: "2025-11-04T12:00:00.000Z"
updatedAt: "2025-11-04T12:00:00.000Z"
---
Controlling access to app resources is crucial for maintaining the security and integrity of your [service apps](https://developers.vtex.com/docs/guides/vtex-io-documentation-service) within the VTEX ecosystem. By implementing appropriate access controls, you can ensure that only authorized entities can access sensitive data and functionalities. When developers implement service apps, they must choose how the app's routes can be accessed. There are two kinds of [policies](https://developers.vtex.com/docs/guides/app-policies): **role-based** and **resource-based**. The following table summarizes how each policy type works.
<table>
<thead>
<tr>
<td></td>
<td><b>Role-based</b></td>
<td><b>Resource-based</b></td>
</tr>
</thead>
<tr>
<td>Requester</td>
<td>Another IO app (by itself or on <a href="https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens" target="_blank">behalf of other apps</a>).</td>
<td>
<ul>
<li>Another IO app (by itself, or <a href="https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens" target="_blank">on behalf of users and other apps</a>)</li>
<li>Admin user</li>
<li>Integrations (<a href="https://help.vtex.com/en/tutorial/api-keys--4bFEmcHXgpNksoePchZyy6" target="_blank">API keys</a>)</li>
</ul>
</td>
</tr>
<tr>
<td>API type</td>
<td>
<ul>
<li>GraphQL</li>
<li>REST</li>
</ul>
</td>
<td>REST</td>
</tr>
<tr>
<td>How other apps access the resource</td>
<td>Adding policies in their <code>manifest.json</code> file and using <a href="https://developers.vtex.com/docs/guides/vtex-io-documentation-clients" target="_blank">clients</a> to make API requests.</td>
<td>Using <a href="https://developers.vtex.com/docs/guides/vtex-io-documentation-clients" target="_blank">clients</a> to make API requests. It isn't necessary to add policies in the <code>manifest.json</code> file.</td>
</tr>
<tr>
<td>How users and integrations (API keys) access the resource</td>
<td>Not applicable.</td>
<td>Making the request, including the <a href="https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens" target="_blank">authentication token</a> in the header.</td>
</tr>
</table>
Policies control access only for the owner of the authentication token. In scenarios where an IO app makes an API call to another app and uses an authentication token in the `VtexIdclientAutCookie` header, the policy will only have an allow or deny effect for the token owner, regardless of whether they are a third-party app, a user, or an API key. Policies won't affect access control for the app making the API call in these scenarios.
## Defining role-based policies
Role-based policies are associated with a [role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc) in the platform. Each policy contains which resources (routes) and actions (HTTP methods) are allowed or denied. Apps must declare role-based policies to securely expose their resources when the requesters aren't explicitly defined. Role-based policies control access to the resource only for other apps.
If you are developing an app that requires access to resources with these policies, you must declare the policies in the `manifest.json` file for the desired resources and access them using a [client](https://developers.vtex.com/docs/guides/vtex-io-documentation-clients). For more information, see [Accessing external resources within a VTEX IO app](https://developers.vtex.com/docs/guides/accessing-external-resources-within-a-vtex-io-app).
Recommendations to use role-based policies:
- The requesters are only apps that make requests independently or [on behalf of other apps](https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens). Don't use role-based policies when requesters are users, integrations, or other [apps making requests on behalf of users](https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens).
- Required for exposing GraphQL endpoints and optional for REST endpoints.
- Compared to [resource-based policies](#defining-resource-based-policies), apps that want to access exposed resources must declare the necessary permissions in the `manifest.json`.
> ℹ️ To define access control for users and integrations, use [resource-based policies](#defining-resource-based-policies) for REST APIs and the [`@auth` directive](https://developers.vtex.com/docs/guides/graphql-authorization-in-io-apps) for GraphQL APIs.
To declare a role-based policy for an app, create a `policies.json` file in the app's root folder. The basic structure of this file is as follows:
```json
{
{
"name": "resolve-graphql",
"description": "Allows access to resolve a graphql request",
"statements": [
{
"effect": "allow",
"actions": ["post", "get"],
"resources": [
"vrn:vtex.store-graphql:{{region}}:{{account}}:{{workspace}}:/_v/graphql"
]
}
]
}
}
```
Note that, in this example, a policy named `resolve-graphql` was declared, allowing access to an app to resolve a GraphQL request.
Besides a `name` and a `description`, this policy contains the `statements` prop.
Statements are used to indicate: "**allow/do not allow** these **actions** to be performed on these **resources** under these **conditions**".
Therefore, considering the given example, the declared `resolve-graphql` policy allows `POST` and `GET` requests to be performed on the `vrn:vtex.store-graphql:{{region}}:{{account}}:{{workspace}}:/_v/graphql` resource.
The keys that compose a statement are:
- `effect`: Describes the effect of allowing (`allow`) or denying (`deny`) a resource to be accessed.
- `actions`: Describes the actions (HTTP methods) related to a given effect and resource.
> ℹ️ Depending on the resource, different actions could be performed on it. For RESTful APIs, this could map to HTTP verbs. However, actions aren't restricted to them, and the service may accept any string as an action.
- `resources`: contains the list of resources expressed by a [VTEX Resource Name (VRN)](https://developers.vtex.com/docs/guides/vtex-io-documentation-vrn) to which the statement refers. A [VTEX Resource Name (VRN)](https://developers.vtex.com/docs/guides/vtex-io-documentation-vrn) is a string that uniquely identifies a resource within the VTEX platform.
## Defining resource-based policies
Resource-based policies are applied to routes defined in the `service.json` file. Routes can be public or private. Public routes are always allowed for everyone and don't require an [authentication token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens). Private routes require authentication, and their policies define which actions (HTTP methods) are permitted by whom. If a private route has no policies, no one is allowed to perform any action with this route.
Apps must declare resource-based policies to securely expose their private resources (routes) for specific requesters (users, integrations, or other apps). Apps accessing the exposed resources don’t need to declare policies in the `manifest.json` file.
Recommendations to use resource-based policies:
- Required when the requesters are users, integrations, or other [apps making requests on behalf of users](https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens). Optional for other apps that make requests by themselves or on [behalf of other apps](https://developers.vtex.com/docs/guides/app-authentication-using-auth-tokens).
- Optional for exposing REST endpoints. Incompatible with GraphQL endpoints.
- Compared to [role-based policies](#defining-role-based-policies), apps exposing resources can control which other apps can access private routes through source-based policies.
To create a resource-based policy, the resource itself must list who it trusts. Therefore, since the resource's routes are declared in a `service.json` file, a resource-based policy must be declared in this file as a `routes` property.
The `service.json` file must have something similar to the following:
```json
{
"routes": {
"new-order": {
"path": "/orders",
"public": false,
"policies": [{
"effect": "allow",
"actions": ["post"],
"principals": [
"vrn:apps:*:*:*:app/example.marketplace@*"
]
}]
}
}
}
```
Note that, in this example, a resource-based policy related to the `/orders` route was declared. The `effect`, `actions`, and `principals` props under `policies` can be translated as: "**allow/do not allow** these **actions** to be performed by these **principals** in this **route**", where principals can be understood as the applications able to make requests to a given resource.
Hence, for the given example, a policy related to the `/orders` resource allows the `example.marketplace` app to perform a `POST` request in its route.
The keys that compose this kind of policy are:
- `effect`: Describes the effect of allowing (`allow`) or denying (`deny`) a principal to perform a set of actions on a route.
- `actions`: Describes the actions related to a given effect, principal, and route.
- `principals`: Contains the list of principals able to perform requests to a given route or not. Like resources, `principals` are also expressed by a [VTEX Resource Name (VRN)](https://developers.vtex.com/docs/guides/vtex-io-documentation-vrn).
> ⚠️ Policies denying access have priority over those allowing access. If actions and principals intersect in different policies of a route, this subset of principals will be denied access to these actions.
### Principal types
The following table summarizes the resource-based policy usage for each type of principal.
| Principal type | `service` (VRN element) | `path` (VRN element) |
| - | - | - |
| Other apps | `apps` | `app/{vendor}.{app-name}@{app-version}` |
| Users | `vtex.vtex-id` | `user/{email}` |
| Integrations (API keys) | `vtex.vtex-id` | `user/vtexappkey-{account}-{hash}` |
The following sections show how VRNs are used for each type of principal, with examples.
#### Other apps
By default, other apps aren't allowed to access private resources exposed through resource-based policies unless they are included in the `principals` list of a policy allowing it (`"effect": "allow"`).
To include other apps in `principals`, use the following VRN syntax:
- Set the `service` element of the VRN to `apps`.
- The `path` element uses the format `app/{vendor}.{app-name}@{app-version}`. It's possible to use the `*` wildcard. For instance:
- `app/*` covers all apps
- `app/{vendor}.*` covers all apps of a specific vendor
- `app/{vendor}.{app-name}@*` covers all versions of a specific app
- `app/{vendor}.{app-name}@{major}.*` covers all versions of a specific app major
The example below illustrates two policies with intersecting principals that use wildcards. The first policy allows all apps to use the `POST` method in a route. The second policy denies access to the same route and method, but for all versions of two specific apps.
```json
{
...
"policies": [{
"effect": "allow",
"actions": ["post"],
"principals": [
"vrn:apps:*:*:*:app/*"
]
},
{
"effect": "deny",
"actions": ["post"],
"principals": [
"vrn:apps:*:*:*:app/{vendor1}.{app-name1}@*",
"vrn:apps:*:*:*:app/{vendor2}.{app-name2}@*"
]
}]
}
```
#### Users and integrations
By default, users and integrations (API keys) aren't allowed to access private resources exposed through resource-based policies unless they are included in the `principals` list of a policy allowing it (`"effect": "allow"`).
To include users and integrations in a principal, use the following VRN syntax:
- Set the `service` element of the VRN as `vtex.vtex-id`.
- The `path` element uses the format `user/{username}`. `{username}` can be the user email or the `appkey` of the integration in the format `vtexappkey-{account}-{hash}`. You can use the `*` wildcard. For example:
- `user/*` covers all users and appkeys
- `user/*@*` covers all users
- `user/*@gmail.com` covers all users with the email domain `gmail.com`
- `user/vtexappkey-*` covers all appkeys
- `user/vtexappkey-{account}-*` covers all appkeys of a specific accountWas this feedback useful?
|
henriquessb
approved these changes
Nov 13, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Relates to the task LOC-22600