# Associate Roles and permissions

An [Associate Role](/api/projects/associate-roles.md#associaterole) groups a set of granular [permissions](/api/projects/associate-roles.md#permission) and is assigned to an Associate within a Business Unit. Roles are how you control what each buyer can do: view their own carts, place orders, approve other people's orders, manage Associates, and so on.

Role design is not just an access-control task. The roles you define here determine who can request quotes and whose orders trigger approval later, so decisions on this page carry through to Module 6 (quotes) and Module 7 (approvals).

## Sellers define every role

commercetools does not ship predefined Associate Roles. As the Seller, you create every role yourself from the permission catalog, using `POST /associate-roles`. The platform's single source of truth for what is grantable is the [Permission](/api/projects/associate-roles.md#permission) enum.

In practice, most B2B implementations converge on a handful of role archetypes. These are roles **you** define; they are not platform defaults, but they are a useful starting point.

| Role archetype | Typical responsibility | Representative permissions |
| --- | --- | --- |
| **Buyer** | Builds carts and places their own orders | `CreateMyCarts`, `UpdateMyCarts`, `CreateMyOrdersFromMyCarts` |
| **Reviewer** | Views the organization's carts and orders without buying | `ViewMyCarts`, `ViewOthersCarts`, `ViewOthersOrders` |
| **Supervisor** | Acts across other Associates' resources and approves orders | `ViewOthersCarts`, `CreateOrdersFromOthersCarts`, `UpdateApprovalFlows` |
| **Business administrator** | Manages the Business Unit and its members | `UpdateBusinessUnitDetails`, `AddChildUnits`, `UpdateAssociates` |

A role is created with a unique, immutable `key`, an optional `name`, and a list of `permissions`.

```http
POST /{projectKey}/associate-roles HTTP/1.1
Content-Type: application/json

{
  "key": "buyer",
  "name": "Buyer",
  "permissions": [
    "ViewMyCarts",
    "CreateMyCarts",
    "UpdateMyCarts",
    "CreateMyOrdersFromMyCarts"
  ]
}
```

Associate Roles do not have to be created through the API. You can also create and manage them in the Merchant Center, which suits teams that configure roles without writing code. A common misconception is that B2B roles and permissions are API-only; the Merchant Center exposes the same configuration.

## The permission naming convention

Permission names follow a predictable pattern that makes them easy to reason about: an **action**, the keyword **`My`** or **`Others`**, and a **resource type**. For example, `UpdateMyOrders` and `ViewOthersCarts`.

- **`My`** permissions grant access to the Associate's own resources.
- **`Others`** permissions grant access to resources that belong to other Associates in the same Business Unit.

A small set of Business Unit permissions do not follow the `My`/`Others` split, because they act on the organization itself rather than on a buyer's resources: `AddChildUnits`, `UpdateAssociates`, `UpdateBusinessUnitDetails`, and `UpdateParentUnit`.

For the complete list of grantable permissions and the canonical naming convention, see the [Permission](/api/projects/associate-roles.md#permission) enum and [Permission naming convention](/api/associates-overview.md#permission-naming-convention) in the API reference.

### Others does not imply My

A key design point: granting an `Others` permission does **not** automatically grant the matching `My` permission. The two are independent, which is what makes fine-grained B2B workflows possible.

For example, an Associate with `CreateMyCarts`, `ViewOthersCarts`, and `CreateOrdersFromOthersCarts` can build their own carts and place orders from carts that other people built, but cannot necessarily place orders from their own carts unless you also grant `CreateMyOrdersFromMyCarts`. You combine `My` and `Others` permissions deliberately to model exactly the workflow you need.

## Make roles buyer-assignable or seller-only

Each role has a `buyerAssignable` flag, which defaults to `true`.

- **`buyerAssignable: true`**: a buyer with the `UpdateAssociates` permission (typically a business administrator) can assign this role to other Associates from a buyer portal.
- **`buyerAssignable: false`**: the role can only be assigned by the Seller through the general endpoint, never by a buyer.

Set `buyerAssignable: false` for sensitive roles you do not want buyers to grant themselves, such as a high-limit approver role. This flag becomes important when you design self-service provisioning on the [Associate provisioning patterns](/learning-model-b2b-commerce/configure-associate-access/associate-provisioning-patterns.md) page.

## Separation of duties

B2B procurement governance usually requires that the person who requests a purchase is not the same person who approves it. The platform does not enforce this for you, but the data model strongly implies the pattern: Approval Rules (Module 7) match a **requester** role against an **approver** role, so those must be distinct roles for the separation to hold.

Design for this now by keeping requesting permissions and approving permissions in separate roles:

- A **buyer** (requester) role gets order-creation permissions such as `CreateMyOrdersFromMyCarts`.
- An **approver** role gets approval permissions such as `UpdateApprovalFlows`, and is deliberately **not** granted to the people who place orders.

If a single role held both the ability to place an order and the ability to approve it, an associate could approve their own purchase, defeating the control.

## Worked example: Pacific Property Group roles

Pacific Property Group is a Company with two Divisions, Residential and Commercial (Module 1). Design its roles so that buying and approving are separated.

- **Division buyer**: `ViewMyCarts`, `CreateMyCarts`, `UpdateMyCarts`, `CreateMyOrdersFromMyCarts`. Assigned to the buyers in each Division so they can build carts and place their own orders. Set `buyerAssignable: true`.
- **Division approver**: `ViewOthersOrders`, `UpdateApprovalFlows`. Assigned to the managers who sign off on orders above a threshold. This role is deliberately **not** given the buyer's order-creation permissions, so an approver cannot place the orders they approve. Set `buyerAssignable: false` so buyers cannot grant approval rights to themselves.
- **Company administrator**: `UpdateBusinessUnitDetails`, `UpdateAssociates`, `AddChildUnits`. Assigned at the parent Company to staff who manage the organization and its members.

With buying and approving in separate roles, you can later write an Approval Rule (Module 7) whose requester is the buyer role and whose approver is the approver role, and the separation of duties holds automatically.

## Key takeaways

- commercetools ships no predefined roles; the Seller defines every Associate Role from the permission catalog, through the API or in the Merchant Center.
- Permission names combine an action, the `My` or `Others` keyword, and a resource type; a few Business Unit permissions act on the organization and have no `My`/`Others` split.
- `Others` permissions do not imply the matching `My` permissions, which enables fine-grained workflow modeling.
- `buyerAssignable` controls whether a buyer administrator can assign a role; set it to `false` for sensitive roles.
- Separate requesting and approving permissions into distinct roles so that Approval Rules can enforce separation of duties later.

## Related pages

- [Area overview page with navigation](/learning-model-b2b-commerce.md)
- [Previous page: Customers and Associates](/learning-model-b2b-commerce/configure-associate-access/customers-and-associates.md)
- [Next page: Inheritance modes](/learning-model-b2b-commerce/configure-associate-access/inheritance-modes.md)