Associates Overview
Overview of the concepts related to Associates, Associate Roles, and Permissions.
An Associate is a Customer acting on behalf of a company. Business Units allow you to model companies in hierarchical structures and define which Associates can represent a company. Each Associate in a Business Unit has a specific set of roles that determines the Permissions they have.
Definitions
Seller
In a B2B context, a seller is a merchant offering goods and services to companies.
Buyer
A buyer is a company or a representative of the company purchasing goods and services from a seller. They are represented by Associates in Business Units.
Business Unit
A Business Unit represents a buyers organization. It can be used to model companies in hierarchical structures and determine which Associates can act on behalf of the company.
Associate
An Associate is a Customer who represents a company. They have specific roles that determine their permissions to access and perform actions, like creating carts or placing orders.
Associate Role
An Associate Role is created and managed by sellers and defines the granular Permissions associated with each role. It is assigned to an Associate in a Business Unit through an AssociateRoleAssignment. Associates and their roles can be inherited within the hierarchy of Business Units.
B2B resources
Carts, Orders, Quotes, and Quote Requests that exist within the context of a Business Unit. In practice, this means the resource has its businessUnit
field set.
Permission
Permissions provide controlled access to B2B resources, and their naming convention represents the action allowed for a given resource type, for example, CreateMyCarts
.
Inheritance
Inheritance refers to the process by which Associates and their roles are passed down within the hierarchy of Business Units.
Associate Roles and Permissions
Associates can be assigned specific roles through an AssociateRoleAssignment, which grants an Associate Role to an Associate within a Business Unit. Each Associate Role includes a set of Permissions that provide controlled access to B2B resources.
The following diagram shows three example Associate Roles, each with a set of Permissions.
Sellers' Role in Managing Permissions
Sellers create and manage Associate Roles, including defining the granular Permissions associated with each role. They can make roles assignable by buyers using the buyerAssignable
property of an Associate Role.
Permission Naming Convention
The naming convention for Permissions represents the action allowed for a given resource type. Most Permission names consist of the action name, either the My
or Others
keyword and the resource type (for example, UpdateMyOrders
, ViewOthersCarts
). Permissions with the My
keyword grant access to an Associate's own resources, while Others
Permissions provide access to resources belonging to other Associates.
Distinct 'My' and 'Others' Permissions
Others
Permissions don't imply My
Permissions. This behavior allows for maximum flexibility in modeling complex B2B use cases. For instance, granting an Associate the CreateMyCart
Permission alongside ViewOthersCarts
and CreateOrdersFromOthersCarts
Permissions enables a setup where buyers can create carts but require approval from others to place an order.
Interacting with B2B resources
The API provides three different ways to access B2B resources:
- Using the general endpoints, such as
/{projectKey}/carts
. - Using the me endpoints, such as
/{projectKey}/me/carts
. - Using the
associate
endpoints, such as/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/carts
.
Through the general endpoints
When accessing resources using the general endpoint, the API has no knowledge of the Associate behind the API call. Therefore, no Associate Role Permissions are validated. As such, the general endpoints are intended for a seller that wants to manage access and permissions outside of Composable Commerce.
Example use case: back office operations, customer support.
Through the me endpoint
When using the me endpoints, the API can derive which Associate is behind a given API call using the password flow token. This allows the API to check whether the Associate has the right level of Permissions to perform actions on a given resource. However, the me
endpoint can only grant access to the Associate's own resources, and not to resources that belong to other Associates.
Example use case: mobile app for buyers to make purchases.
Through the associate endpoint
The associate
endpoints require an Associate to be specified as a URL parameter alongside a Business Unit that the Associate's Permissions should be validated against. These endpoints are for sellers that want to provide controlled access for their buyers using Associate Role Permissions.
Example use case: B2B storefront.
Permission evaluation
Permission evaluations and requirements differ based on the endpoint type. The following table provides an overview of the types of Permissions required depending on which method is used to access a resource.
Endpoint type | Permission evaluation | Additional requirements |
---|---|---|
General endpoints | None | If customerId and businessUnit are both present on the resource, then the Customer must be an Associate of the Business Unit. |
me endpoints for B2B resources (for example, My Carts) | My Permissions | If customerId and businessUnit are both present on the resource, then the Customer must be an Associate of the Business Unit. |
me endpoints for Business Units (My Business Units) | Business Unit Permissions | The Customer must be an Associate of the Business Unit. |
associate endpoints for B2B resources | My , Others Permissions | The Associate must be a member of the Business Unit. |
associate endpoints for Business Units | Business Unit Permissions | The Associate must be a member of the Business Unit. |
On the me endpoints
The me
endpoints validate that the acting Associate has sufficient Permissions on a given B2B resources. In addition, the Associate must be a Customer on the resource and be an Associate of the referenced Business Unit.
The me
endpoints do not validate View
Permissions. Therefore, an Associate can view all resources available on the me endpoints, regardless of their Permissions.
Removing an Associate from a Business Unit does not revoke their access to the Carts, Orders, Quotes, and Quote Requests associated with it. The Associate must also be explicitly removed from the entity to fully restrict their access.
My Business Unit
When interacting with Business Units using the My Business Unit endpoints, the API performs validations on certain actions to ensure that the Associate has the correct Business Unit Permissions.
Permission | Required for |
---|---|
AddChildUnits | Creating and assigning a new child unit to a parent unit. |
UpdateAssociates | changeAssociate, removeAssociate update actions, and creating an Associate for a BusinessUnit. |
UpdateParentUnit | changeParentUnit update action. |
UpdateBusinessUnitDetails | Update actions not related to Associate management, or hierarchical changes (such as changeParentUnit). |
My Carts
For B2B Carts, the My Carts endpoints perform validations to ensure that the Associate has the correct CartPermissions.
Permission | Required for |
---|---|
CreateMyCarts | Creating a Cart. |
UpdateMyCarts | Updating a Cart. |
DeleteMyCarts | Deleting a Cart. |
Additionally, the Customer on the Cart must be an Associate of the referenced Business Unit.
My Quotes
For B2B Quotes, the My Quotes endpoints perform validations to ensure that the Associate has the correct QuotePermissions.
Permission | Required for |
---|---|
AcceptMyQuotes | Accepting a Quote. |
DeclineMyQuotes | Declining a Quote. |
RenegotiateMyQuotes | Renegotiating a Quote. |
My Quote Requests
For B2B Quote Requests, the My Quote Requests endpoints perform validations to ensure that the Associate has the correct QuoteRequestPermissions.
Permission | Required for |
---|---|
CreateMyQuoteRequestsFromMyCarts | Creating a Quote Request. |
UpdateMyQuoteRequests | Updating a Quote Request. |
My Orders
For B2B Orders, the My Orders endpoints perform validations to ensure that the Associate has the correct OrderPermissions.
Permission | Required for |
---|---|
CreateMyOrdersFromMyCarts | Creating an Order from a Cart, and creating an Order in Store from a Cart. |
CreateMyOrdersFromMyQuotes | Creating an Order from a Quote. |
On the associate endpoints
The associate
endpoints validate that the acting Associate has sufficient Permissions on a given resource. In addition, the Associate must have access to the referenced Business Unit. In contrast to the me
endpoints, the associate
endpoints can also provide access to resources that do not belong to the Associate directly. For example, the ViewOthersCarts
Permission allows an Associate to view B2B Carts where the Customer on the Cart is another Associate.
Associate Carts
For B2B Carts, the Associate Carts endpoints perform validations to ensure that the Associate has the correct Cart Permissions.
Permission | Required for |
---|---|
ViewMyCarts or ViewOthersCarts | Getting a Cart. |
CreateMyCarts or CreateOthersCarts | Creating a Cart. |
UpdateMyCarts or UpdateOthersCarts | Updating a Cart. |
DeleteMyCarts or DeleteOthersCarts | Deleting a Cart. |
Associate Quotes
For B2B Quotes, the Associate Quotes endpoints perform validations to ensure that the Associate has the correct Quote Permissions.
Permission | Required for |
---|---|
ViewMyQuotes or ViewOthersQuotes | Getting a Quote. |
AcceptMyQuotes or AcceptOthersQuotes | Accepting a Quote. |
DeclineMyQuotes or DeclineOthersQuotes | Declining a Quote. |
RenegotiateMyQuotes or RenegotiateOthersQuotes | Renegotiate a Quote. |
ReassignMyQuotes or ReassignOthersQuotes | Reassigning a Quote. |
Associate Quote Requests
For B2B Quote Requests, the Associate Quote Requests endpoints perform validations to ensure that the Associate has the correct Quote Request Permissions.
Permission | Required for |
---|---|
ViewMyQuoteRequests or ViewOthersQuoteRequests | Getting a Quote Request. |
CreateMyQuoteRequestsFromMyCarts or CreateQuoteRequestsFromOthersCarts | Creating a Quote Request. |
UpdateMyQuoteRequests or UpdateOthersQuoteRequests | Updating a Quote Request. |
Associate Orders
For B2B Orders, the Associate Orders endpoints perform validations to ensure that the Associate has the correct Order Permissions.
Permission | Required for |
---|---|
ViewMyOrders or ViewOthersOrders | Getting an Order. |
CreateMyOrders or CreateOthersOrders | Creating a Order. |
UpdateMyOrders or UpdateOthersOrders | Updating an Order. |
Associate Business Units
The Associate Business Unit endpoints perform validations to ensure that the Associate has the correct Business Unit Permissions.
Permission | Required for |
---|---|
AddChildUnits | Creating and assigning a new child unit to a parent unit. |
UpdateAssociates | addAssociate, setAssociates, changeAssociate, and removeAssociate update actions. |
UpdateParentUnit | changeParentUnit update action. |
UpdateBusinessUnitDetails | Update actions not related to Associate management, or hierarchical changes (such as changeParentUnit). |
Inheritance of Associates and their roles
Associates and their roles can be inherited within the hierarchy of Business Units. The inheritance behavior is determined by the inheritance
property of individual AssociateRoleAssignments together with the AssociateMode of a Business Unit.
Conditions for inheritance
When the AssociateMode of a Business Unit is set to Explicit
, the Business Unit is not allowed to inherit any Associates. In this case, only Associates defined directly on the Business Unit can act on its behalf. With the ExplicitAndFromParent
AssociateMode, the Business Unit can have both directly assigned Associates and inherited ones from a parent unit.
For a Business Unit to inherit Associates from a parent unit, the following two conditions must be met:
- The AssociateMode of the Business Unit must be set to
ExplicitAndFromParent
, allowing the Business Unit to inherit Associates. - A parent unit of the Business Unit must have at least one Associate with an inheritable role, meaning that the
inheritance
property of the AssociateRoleAssignment is set toEnabled
.
The following diagram illustrates how Business Units with ExplicitAndFromParent
AssociateMode inherit Associates from parents, whilst a Business Unit with `Explicit
AssociateMode does not.
Eventual consistency of inherited Associates
The inheritedAssociates
array of a Business Unit contains the Associates that are inherited. In cases where inheritance applies, this property is automatically populated by a background task. It is updated each time an Associate in a parent Business Unit is added, updated, or removed. However, since this process is subject to eventual consistency, changes in inherited roles might have a delayed effect on role evaluations.
Accumulative permissions of inherited roles
The Permissions of an Associate are the sum of all permissions included on the Associate Role assigned to the Associate directly, and those from inherited roles. The following example demonstrates how permissions accumulate.
Preventing inheritance
By setting the AssociateMode of a Business Unit to Explicit
, the inheritance mechanism will be disabled for all Associates of that unit. To prevent the inheritance of a single Associate, disable the inheritance property for all assigned roles of that Associate. This ensures that the Associate is not inherited by any child Business Units. If an Associate is both inherited and explicitly defined in the same Associate Role, the explicitly defined AssociateRoleAssignment determines inheritance.