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 to Enabled.

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.