Manage company roles
Within a company, customers may have different job roles, levels of responsibility, and access to information about their company. Magento Commerce for B2B defines several types of system resources, and the Company Admin (or an integration that operates on the behalf of the Company Admin) grants or denies access to these resources using company roles. The Company Admin has access to all resources.
Magento Commerce for B2B defines the following types of resources:
- Sales
- Negotiable quotes
- Company profile
- Company user management
- Company credit
Each of these resources contains a hierarchy of other resources. When a Company Admin grants or blocks access to a resource from the store UI, the action applies to all sub-resources, unless explicitly overridden. However, if you grant or block accesss using web APIs, you must specify each resource individually.
The following table lists all the resources that are available to the customers defined with a company. To visualize the resource hierarchy, log in to a store as the Company Admin and select Roles and Permissions, then click the Edit action next to the Default User role.
Resource name | Display name | Hierarchy level |
---|---|---|
Magento_Company::index | All | 1 |
Magento_Sales::all | Sales | 2 |
Magento_Sales::place_order | Checkout (place order) | 3 |
Magento_Sales::payment_account | Use Pay On Account method | 4 |
Magento_Sales::view_orders | View orders | 3 |
Magento_Sales::view_orders_sub | View orders of subordinate users | 4 |
Magento_NegotiableQuote::all | Quotes | 2 |
Magento_NegotiableQuote::view_quotes | View | 3 |
Magento_NegotiableQuote::manage | Request, Edit, Delete | 4 |
Magento_NegotiableQuote::checkout | Checkout with Quote | 4 |
Magento_NegotiableQuote::view_quotes_sub | View quotes of subordinate users | 4 |
Magento_Company::view | Company Profile | 2 |
Magento_Company::view_account | Account Information (View) | 3 |
Magento_Company::edit_account | Edit | 4 |
Magento_Company::view_address | Legal Address (View) | 3 |
Magento_Company::edit_address | Edit | 4 |
Magento_Company::contacts | Contacts (View) | 3 |
Magento_Company::payment_information | Payment Information (View) | 3 |
Magento_Company::user_management | Company User Management | 2 |
Magento_Company::roles_view | View roles and permissions | 3 |
Magento_Company::roles_edit | Manage roles and permissions | 4 |
Magento_Company::users_view | View users and teams | 3 |
Magento_Company::users_edit | Manage users and teams | 4 |
Magento_Company::credit | Company credit | 2 |
Magento_Company::credit_history | view | 3 |
Manage company roles
The Company Admin controls the possible actions for each customer within the company by creating common roles with embedded permissions and then assigning them to company users. In most cases, a few roles will be sufficient to cover all the different possible combinations of permissions needed for a company.
Service Name
companyRoleRepositoryV1
REST Endpoints
RoleInterface Parameters
The following table lists the parameters defined in RoleInterface
.
Name | Description | Format | Requirements |
---|---|---|---|
id | The role ID | integer | Required for updates and deletes |
role_name | The label assigned to the role | string | Required to create a role |
permissions | A list of resources and permissions granted to the role. See the Permissions array table below for details. | Array[string] | Required to create a role |
company_id | The company associated with this role | integer | Required to create a role |
Permissions array
Name | Description | Format | Requirements |
---|---|---|---|
id | The permission ID generated by Magento. | integer | Required for updates and deletes |
role_id | The role ID to which the permission applies. | integer | Required to create a role |
resource_id | The internal name of a Magento resource, such as Magento_Sales::place_order . | string | Required |
permission | Either allow or deny . | string | Required |
Create a role
This example creates a role named “Junior Buyer”. It allows the assignee to access to all Sales resources except “View orders of subordinate users”.
All resouces that are not explicitly allowed are denied. You must specify the Magento_Company::index
resource in all calls.
Sample Usage
POST /V1/company/role
Payload
Response
Update a role
Each update call must include all resources the assignee will have access to.
This example call adds access to all Negotiable Quote resources except “View quotes of subordinate users” to the Junior Buyer role.
Sample Usage
PUT /V1/company/role/6
Payload
Response
Return all information about a role
This call returns the id
, role name, and set of permissions defined within the specified role_id
.
Sample Usage
GET /V1/company/role/6
Payload
None
Response
Delete a role
You cannot delete a role if it is the only role defined within the company.
Sample Usage
DELETE /V1/company/role/5
Payload
None
Response
true
, indicating the request was successful
Search for a role
The following call returns all roles that have been created for a company (company_id
= 2
).
See Search using REST APIs for information about constructing a search query.
Sample Usage
GET /V1/company/role?searchCriteria[filter_groups][0][filters][0][field]=company_id&searchCriteria[filter_groups][0][filters][0][value]=2&searchCriteria[filter_groups][0][filters][0][condition_type]=eq
Payload
None
Response