Apps may need to access resources that are external to the app itself. An external resource could be:

• Endpoints exposed by other VTEX IO apps (REST or GraphQL)
• VTEX Core Commerce APIs
• Third-party endpoints outside VTEX, such as a payment provider or an external marketplace.

To access these resources, apps must declare policies in the policies list of the manifest.json file.

This article explains when policies are required and how each policy type should be declared.

Apps need to declare policies to gain access to external resources, which include:

• Access to specific content (file, image, etc.)
• Access to VTEX Core Commerce APIs
• Access to resources exposed through role-based policies

Declaring policies is not required for resources exposed through resource-based policies, since these policies already define which apps are allowed.

VTEX IO supports three types of access policies when interacting with external resources:

• License Manager policies
• Policies exposed by VTEX IO apps (role-based)
• Outbound-access policies

Each type is declared differently and applies to specific use cases, as described below.

License Manager policies refer to native VTEX resources and have predefined names.

To declare a policy of this type in the manifest.json, use the policy name in the "name" field. See the example below:

You can find all available policy names in the Key column of the License Manager resources table. For more details, see the Policies from License Manager article.

These policies grant access to app routes exposed with role-based policies. This policy type is used to access GraphQL queries exposed by IO 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:

To find 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-graphql app.

Outbound-access policies should be used only when the other two types do not apply. They grant access to explicit URLs, often for external (non-VTEX) services.

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.

Example

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: