new: storefront permissions guide #2217
+82
−0
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,82 @@ | ||||||
| --- | ||||||
| title: "Storefront Permissions" | ||||||
| slug: "storefront-permissions" | ||||||
| hidden: false | ||||||
| excerpt: "Learn how to manage user access and roles within the storefront using the Storefront Permissions API for B2B scenarios." | ||||||
| createdAt: "2025-10-09T00:00:00.000Z" | ||||||
| updatedAt: "2025-10-09T00:00:00.000Z" | ||||||
| --- | ||||||
|
|
||||||
| The [Storefront Permissions API](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#overview) provides a structured way to manage user access and roles within the storefront. It enables organizations to define and enforce authorization policies by controlling which actions users can perform. | ||||||
|
There was a problem hiding this comment. [markdownlint-fix] reported by reviewdog 🐶
Suggested change
|
||||||
|
|
||||||
| With the Storefront Permissions API, you can: | ||||||
|
|
||||||
| * Assign and revoke roles for storefront users. | ||||||
| * Validate access by checking whether a user has permission to perform a specific action. | ||||||
| * Retrieve details about user roles and permissions. | ||||||
| * Manage access to resources such as orders, addresses, authentication settings, and payment methods. | ||||||
|
|
||||||
| ## Key concepts | ||||||
|
|
||||||
| * **Storefront resources**: Fine-grained permissions that define a specific capability in the storefront (e.g., `PlaceOrders`, `ApproveOrders`, `ManageAddresses`). | ||||||
| * **Storefront roles**: Logical groupings of resources that represent common permission sets (e.g., `Buyer`, `Order Approver`, `Organizational Unit Admin`). | ||||||
| * **Storefront users**: Storefront identities (customers or organization members) to whom roles and resources are assigned. | ||||||
|
|
||||||
| ## Use cases | ||||||
|
|
||||||
| This functionality is particularly relevant for B2B scenarios, where multiple users within the same organization may require differentiated levels of access depending on their role in the purchasing process. | ||||||
|
|
||||||
| The Storefront Permissions API supports a wide range of business scenarios by enabling control over user access, for example: | ||||||
|
|
||||||
| * Granting buyers the ability to place orders while restricting order approvals to designated approvers. | ||||||
| * Allowing managers to oversee all orders within their organizational unit. | ||||||
| * Enabling administrators to configure organizational structures, contracts, and user access. | ||||||
|
|
||||||
| ## Before you begin | ||||||
|
|
||||||
| * All endpoints require the Storefront Permissions feature to be enabled for your account. Requests to accounts without this feature enabled will receive a “Feature not enabled for this account” response. | ||||||
|
|
||||||
| * Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run requests to the License Manager API as listed 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` [Check storefront user resource access](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#get-/api/license-manager/storefront/users/-userId-/resources/-resourceKey-/granted) `GET` [Fetch storefront user roles by ID](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#get-/api/license-manager/storefront/users/-userId-/roles) `GET` [Fetch storefront user roles by email](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#get-/api/license-manager/storefront/users/-email-/roles) `GET` [Fetch storefront user details](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#get-/api/license-manager/storefront/users/-userId-) | | ||||||
| | License Manager | Services access control | Edit Storefront User Permissions | `POST` [Create storefront user](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#post-/api/license-manager/storefront/users/) `POST` [Assign storefront role to user](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#post-/api/license-manager/storefront/roles/assign) `DELETE` [Revoke storefront role from user](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#delete-/api/license-manager/storefront/roles/revoke) `DELETE` [Remove storefront user](https://developers.vtex.com/docs/api-reference/storefront-permissions-api#delete-/api/license-manager/storefront/remove/users/-userId-) | | ||||||
|
|
||||||
| To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication). | ||||||
|
|
||||||
| ## Available storefront resources | ||||||
|
|
||||||
| The following resource keys are available in the system: | ||||||
|
|
||||||
| | Resource Key | Description | | ||||||
| | :---- | :---- | | ||||||
| | ManageOrganizationAndContract | Allows management of the organization's structure, contracts, and related settings. | | ||||||
| | PlaceOrders | Grants the ability to create and submit orders within the system. | | ||||||
| | ViewMyContractOrders | Enables users to see orders placed under their assigned contract. | | ||||||
| | ViewMyOrgUnitOrders | Allows users to view all orders within their organizational unit. | | ||||||
| | ModifyOrders | Provides permission to use the change order feature for all orders that the user has access to. | | ||||||
| | ApproveOrders | Grants the ability to approve or reject orders based on predefined workflows. | | ||||||
| | ManageAddresses | Add the address during checkout and save it for that contract / organization unit. | | ||||||
| | UseAdHocCard | Grants permission to use a new credit card at checkout. | | ||||||
| | SavePrivateCard | Grants permission to save a new card for the user's use only. | | ||||||
| | ViewProfile | Allows access to view the profile information. | | ||||||
| | ManageAuthentication | Provides access to authentication settings. | | ||||||
| | ViewMyCards | Enables users to view their payment cards. | | ||||||
| | ViewAddresses | Allows users to manage and update their saved addresses. | | ||||||
|
|
||||||
| ## Predefined storefront roles | ||||||
|
|
||||||
| The system comes with these predefined storefront roles, each with specific permissions: | ||||||
|
|
||||||
| | Predefined storefront role | Storefront role ID | Description | Associated resources | | ||||||
| | :---- | :---- | :---- | :---- | | ||||||
| | Organizational Unit Admin | 1 | Manages the organization's structure, contracts, and related settings. | ManageOrganizationAndContract | | ||||||
| | Order Approver | 2 | Can approve or reject orders based on predefined workflows. | ApproveOrders | | ||||||
| | Order Modifier | 3 | Can use the change order feature for all orders they have access to. | ModifyOrders | | ||||||
| | Buyer | 4 | Can create and submit orders within the system. | PlaceOrders | | ||||||
| | Personal Cards User | 5 | Can use a new credit card at checkout and save cards for personal use only. | UseAdHocCard, SavePrivateCard | | ||||||
| | Contract Manager | 6 | Can view orders placed under their assigned contract. | ViewMyContractOrders | | ||||||
| | Buyer Organization Manager | 7 | Can view all orders within their organizational unit. | ViewMyOrgUnitOrders | | ||||||
| | Contract Viewer | 8 | Can view profiles, payment cards, and addresses. | ViewProfile, ViewMyCards, ViewAddresses | | ||||||
| | Address Manager | 9 | Can add and manage addresses during checkout. | ManageAddresses | | ||||||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[markdownlint] reported by reviewdog 🐶
MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]