This feature is available only for stores using B2B Buyer Portal, currently available for selected accounts.

The B2B Buyer Portal permission model is built on predefined storefront roles and resources provided by VTEX. When the native set does not cover all the permission scenarios your business requires, you can extend it by creating custom storefront roles and resources scoped to your account.

Custom storefront roles and resources follow the same model as native ones, but are fully owned and managed by your account via the Storefront Roles API.

• Custom storefront resource: An account-defined permission key representing a specific capability not covered by the native VTEX storefront resources. Once created, a storefront resource key is immutable.
• Custom storefront role: An account-defined grouping of storefront resources. Custom storefront roles can include both native VTEX storefront resources and custom storefront resources belonging to your account.

All endpoints require the Storefront Roles feature to be enabled on your account. Requests sent to accounts without this feature return a 403 Forbidden error.

Any user or API key must have the appropriate License Manager resources as described in the table below. Otherwise, they will receive a status code 403 error.

Product	Category	Resource	Associated endpoints
License Manager	Services access control	View Storefront User Permissions	GET List storefront roles GET Get storefront role GET List storefront resources
License Manager	Services access control	Edit Storefront User Permissions	POST Create custom storefront role PUT Update custom storefront role DELETE Delete custom storefront role POST Create custom storefront resource DELETE Delete custom storefront resource

To learn more about machine authentication at VTEX, see Authentication overview.

Keep the following limits and rules in mind before creating custom storefront roles and resources:

• An account can have a maximum of 10 custom storefront resources.
• Custom storefront resource keys must be 5–80 characters, unique within the account, and must not match any native VTEX storefront resource key. Keys are treated as case-insensitive and can't be changed after creation. See the Storefront Roles guide for the list of native storefront resource keys to avoid conflicts.
• Custom storefront role names must be 1–100 characters, unique within the account, and must not match any native VTEX storefront role name. See the Storefront Roles guide for the list of native storefront role names.
• A custom storefront role must be unassigned from all users before it can be deleted.
• Native storefront roles and resources can't be modified or deleted through the custom storefront role and resource endpoints.

Custom storefront resources define new permission keys that your account can use when building custom storefront roles.

Use POST Create custom storefront resource to create a new storefront resource key for your account.

Use GET List storefront resources before creating a storefront resource to verify that your intended key does not conflict with any existing native or custom storefront resource key.

Example request body:

Example response — 201 Created:

Use GET List storefront resources to retrieve all storefront resources visible to the account, including native VTEX storefront resources and your account's own custom storefront resources. An empty array is a valid response.

Example response — 200 OK:

Use DELETE Delete custom storefront resource to permanently remove a custom storefront resource from the account.

A storefront resource can't be deleted while it is assigned to any custom storefront role. Remove the storefront resource from all storefront roles that reference it before attempting to delete it. Native VTEX storefront resources can't be deleted.

Custom storefront roles group storefront resources into named permission sets that can then be assigned to storefront users.

Use POST Create custom storefront role to create a new storefront role and assign storefront resources to it.

Example request body:

Example response — 201 Created:

Use GET List storefront roles to retrieve all storefront roles visible to the account, including native VTEX storefront roles and your account's own custom storefront roles. An empty array is a valid response.

Example response — 200 OK:

Use GET Get storefront role to retrieve the details of a specific storefront role by its numeric ID, including its name, whether it is custom or native, and its associated storefront resources.

Example response — 200 OK:

Use PUT Update custom storefront role to update a custom storefront role's name or storefront resource assignments.

The Resources array in the request body replaces the storefront role's current storefront resource list entirely. Include all storefront resource IDs the storefront role should have after the update, not just the ones being added or removed. Native VTEX storefront roles can't be updated through this endpoint.

Example request body:

Example response — 200 OK:

Use DELETE Delete custom storefront role to permanently remove a custom storefront role from the account.

The storefront role must be unassigned from all storefront users before it can be deleted. Native VTEX storefront roles can't be deleted.

Once a custom storefront role is created, you can assign it to storefront users using the existing storefront role assignment endpoints, the same way you would assign any predefined storefront role. See Storefront Roles for details on the assignment endpoints and the required permissions.