Enhanced permissions management for companies

2 May 2023

Composable Commerce

HTTP API

New feature

Deprecation

B2BCustomersCartsOrdersQuotesGraphQL

The new Associate Roles API provides B2B customers with the flexibility to define and manage the permissions of their Associates. The feature allows the configuration of granular permissions that provide controlled access to Business Units, Carts, Orders, Quotes, and Quote Requests. Additionally, roles can be inherited from a parent Business Unit by its children.

This feature replaces the less flexible AssociateRole enum with Buyer and Admin values. This type alongside the roles field on Associate and AssociateDraft is now deprecated and will be completely removed on 02 August 2023.

In addition to the Associate Roles API, a new set of associate endpoints can be used to validate that an Associate has sufficient permissions on a given resource. These endpoints are available for Business Units, Carts, Orders, Quotes, and Quote Requests and perform permission evaluation checks based on an associateId.

These features are part of Composable Commerce for B2B and will be subject to additional terms and pricing.

Changes:

[API] Added Associate Roles API.
[API] Added Associate Carts, Associate Orders, Associate Quote Requests, Associate Quotes, and Associate BusinessUnit endpoints.
[API] Added BusinessUnitAssociateMode, AssociateRoleInheritanceMode, AssociateRoleAssignment, and AssociateRoleAssignmentDraft, InheritedAssociate, and InheritedAssociateRoleAssignment types to BusinessUnit.
[API] Added inheritedAssociates and associateMode fields to BusinessUnit.
[API] Added associateMode fields to BusinessUnitDraft.
[API] Added associateRoleAssignments field to Associate and AssociateDraft.
[API] AddedassociateRoleAssignments to MyBusinessUnitAssociateDraft.
[API] Deprecated AssociateRole enum with Admin and Buyer values.
[API] Deprecated roles and inheritedAssociates field on Associate and AssociateDraft.
[API] Added Associate Role Messages.
[API] Added BusinessUnitAssociateModeChanged Message.
[API] Added myBusinessUnitAssociateRoleOnCreation to BusinessUnitConfiguration in Project settings.
[GraphQL API] Added the following types to the GraphQL schema: AddAssociateRolePermission, AsAssociate, AsAssociateArgument, AssociateInheritanceMode, AssociateRole, AssociateRoleAssignment, AssociateRoleAssignmentDraft, AssociateRoleBuyerAssignableChanged, AssociateRoleCreated, AssociateRoleDeleted, AssociateRoleDraft, AssociateRoleNameSet, AssociateRolePermissionAdded, AssociateRolePermissionRemoved, AssociateRolePermissionsSet, AssociateRoleQueryResult, AssociateRoleUpdateAction, BusinessUnitAssociateMode, BusinessUnitAssociateModeChanged, ChangeAssociateRoleBuyerAssignable, ChangeBusinessUnitAssociateMode, InheritedAssociate, InheritedAssociateRoleAssignment, Permission, RemoveAssociateRolePermission, SetAssociateRoleCustomField, SetAssociateRoleCustomType, SetAssociateRoleName, SetAssociateRolePermissions, SetProjectSettingsMyBusinessUnitAssociateRoleOnCreation.
[GraphQL API] Changed the BusinessUnitDraft type:
- Input field associateMode was added to BusinessUnitDraft type
[GraphQL API] Changed the BusinessUnit type:
- Added the inheritedAssociates field to the BusinessUnit type.
- Added the associateMode field to the BusinessUnit type.
[GraphQL API] Changed the Associate type:
- Added the associateRoleAssignments field to the Associate type.
- Field roles was deprecated in Associate type
[GraphQL API] Changed the AssociateDraft type:
- Input field associateRoleAssignments was added to AssociateDraft type
- Input field roles was deprecated in AssociateDraft type
[GraphQL API] Changed the BusinessUnitConfiguration type:
- Added the myBusinessUnitAssociateRoleOnCreation field to the BusinessUnitConfiguration type.
- Added the myBusinessUnitAssociateRoleOnCreationRef field to the BusinessUnitConfiguration type.
[GraphQL API] SimpleAssociateRole type was deprecated
[GraphQL API] Changed the Query type:
- Added the asAssociate field to the Query type.
- Added the associateRole field to the Query type.
- Added the associateRoles field to the Query type.
[GraphQL API] Changed the Mutation type:
- Argument asAssociate was added to Mutation.updateBusinessUnit field
- Added the updateAssociateRole field to the Mutation type.
- Argument asAssociate was added to Mutation.createOrderFromCart field
- Argument asAssociate was added to Mutation.deleteCart field
- Argument asAssociate was added to Mutation.createBusinessUnit field
- Argument asAssociate was added to Mutation.updateQuoteRequest field
- Argument asAssociate was added to Mutation.createOrderFromQuote field
- Argument asAssociate was added to Mutation.createCart field
- Argument asAssociate was added to Mutation.updateOrder field
- Added the deleteAssociateRole field to the Mutation type.
- Argument asAssociate was added to Mutation.updateQuote field
- Argument asAssociate was added to Mutation.createQuoteRequest field
- Added the createAssociateRole field to the Mutation type.
- Argument asAssociate was added to Mutation.updateCart field
[GraphQL API] Changed the ProjectSettingsUpdateAction type:
- Input field setMyBusinessUnitAssociateRoleOnCreation was added to ProjectSettingsUpdateAction type
[GraphQL API] Changed the BusinessUnitUpdateAction type:
- Input field changeAssociateMode was added to BusinessUnitUpdateAction type

The following changes were introduced in terms of GraphQL SDL:

extend type Query {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  asAssociate(businessUnitKey: KeyReferenceInput!, associateId: String!): AsAssociate!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRole(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): AssociateRole

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRoles(where: String, sort: [String!], limit: Int, offset: Int): AssociateRoleQueryResult!
}

extend type BusinessUnit {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateMode: BusinessUnitAssociateMode

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  inheritedAssociates: [InheritedAssociate!]
}

extend type Associate {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRoleAssignments: [AssociateRoleAssignment!]
}

extend type Mutation {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  createAssociateRole(draft: AssociateRoleDraft!): AssociateRole

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  deleteAssociateRole(version: Long!, personalDataErasure: Boolean = false,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): AssociateRole

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  updateAssociateRole(version: Long!, actions: [AssociateRoleUpdateAction!]!,

    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): AssociateRole
}

extend type BusinessUnitConfiguration {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  myBusinessUnitAssociateRoleOnCreation: AssociateRole

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  myBusinessUnitAssociateRoleOnCreationRef: KeyReference
}

extend input BusinessUnitDraft {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateMode: BusinessUnitAssociateMode
}

extend input AssociateDraft {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRoleAssignments: [AssociateRoleAssignmentDraft!]
}

extend input ProjectSettingsUpdateAction {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setMyBusinessUnitAssociateRoleOnCreation: SetProjectSettingsMyBusinessUnitAssociateRoleOnCreation
}

extend input BusinessUnitUpdateAction {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  changeAssociateMode: ChangeBusinessUnitAssociateMode
}

input AddAssociateRolePermission {
  permission: Permission!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type AsAssociate implements CartQueryInterface & OrderQueryInterface & QuoteQueryInterface & QuoteRequestQueryInterface {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  cart(id: String!): Cart

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  carts(where: String, sort: [String!], limit: Int, offset: Int): CartQueryResult!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  order(
    "Queries with specified ID"
    id: String, orderNumber: String): Order

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  orders(where: String, sort: [String!], limit: Int, offset: Int): OrderQueryResult!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  quoteRequest(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): QuoteRequest

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  quoteRequests(where: String, sort: [String!], limit: Int, offset: Int): QuoteRequestQueryResult!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  quote(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): Quote

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  quotes(where: String, sort: [String!], limit: Int, offset: Int): QuoteQueryResult!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  businessUnit(
    "Queries with specified ID"
    id: String,

    "Queries with specified key"
    key: String): BusinessUnit

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  businessUnits(where: String, sort: [String!], limit: Int, offset: Int): BusinessUnitQueryResult!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input AsAssociateArgument {
  businessUnitKey: KeyReferenceInput!
  associateId: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum AssociateInheritanceMode {
  Disabled
  Enabled
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type AssociateRole implements Versioned {
  key: String!
  buyerAssignable: Boolean!
  name: String
  permissions: [Permission!]!
  custom: CustomFieldsType
  id: String!
  version: Long!
  createdAt: DateTime!
  lastModifiedAt: DateTime!
  createdBy: Initiator
  lastModifiedBy: Initiator
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type AssociateRoleAssignment {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRoleRef: KeyReference

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRole: AssociateRole!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  inheritance: AssociateInheritanceMode
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input AssociateRoleAssignmentDraft {
  associateRole: ResourceIdentifierInput!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  inheritance: AssociateInheritanceMode
}

type AssociateRoleBuyerAssignableChanged implements MessagePayload {
  buyerAssignable: Boolean!
  type: String!
}

type AssociateRoleCreated implements MessagePayload {
  associateRole: AssociateRole!
  type: String!
}

type AssociateRoleDeleted implements MessagePayload {
  type: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input AssociateRoleDraft {
  key: String!
  name: String
  buyerAssignable: Boolean!
  permissions: [Permission!]
  custom: CustomFieldsDraft
}

type AssociateRoleNameSet implements MessagePayload {
  name: String
  type: String!
}

type AssociateRolePermissionAdded implements MessagePayload {
  permission: Permission!
  type: String!
}

type AssociateRolePermissionRemoved implements MessagePayload {
  permission: Permission!
  type: String!
}

type AssociateRolePermissionsSet implements MessagePayload {
  permissions: [Permission!]
  type: String!
}

type AssociateRoleQueryResult {
  offset: Int!
  count: Int!
  total: Long!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [AssociateRole!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input AssociateRoleUpdateAction {
  addPermission: AddAssociateRolePermission
  changeBuyerAssignable: ChangeAssociateRoleBuyerAssignable
  removePermission: RemoveAssociateRolePermission
  setCustomField: SetAssociateRoleCustomField
  setCustomType: SetAssociateRoleCustomType
  setName: SetAssociateRoleName
  setPermissions: SetAssociateRolePermissions
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum BusinessUnitAssociateMode {
  Explicit
  ExplicitAndFromParent
}

type BusinessUnitAssociateModeChanged implements MessagePayload {
  associateMode: BusinessUnitAssociateMode!
  oldAssociateMode: BusinessUnitAssociateMode
  type: String!
}

input ChangeAssociateRoleBuyerAssignable {
  buyerAssignable: Boolean!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ChangeBusinessUnitAssociateMode {
  associateMode: BusinessUnitAssociateMode!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type InheritedAssociate {
  associateRoleAssignments: [InheritedAssociateRoleAssignment!]!
  customerRef: Reference
  customer: Customer
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type InheritedAssociateRoleAssignment {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRoleRef: KeyReference!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  associateRole: AssociateRole!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  sourceRef: KeyReference!

  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  source: BusinessUnit!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum Permission {
  CreateMyOrdersFromMyQuotes
  CreateMyQuoteRequestsFromMyCarts
  CreateMyCarts
  CreateOrdersFromOthersCarts
  DeclineOthersQuotes
  UpdateMyCarts
  ViewOthersQuotes
  RenegotiateMyQuotes
  UpdateParentUnit
  CreateOthersCarts
  UpdateBusinessUnitDetails
  AcceptMyQuotes
  RenegotiateOthersQuotes
  UpdateOthersCarts
  DeleteOthersCarts
  DeclineMyQuotes
  ViewMyCarts
  AddChildUnits
  DeleteMyCarts
  UpdateAssociates
  AcceptOthersQuotes
  ViewOthersOrders
  ViewOthersCarts
  UpdateMyQuoteRequests
  CreateQuoteRequestsFromOthersCarts
  ViewMyQuotes
  ViewMyQuoteRequests
  CreateMyOrdersFromMyCarts
  UpdateOthersOrders
  UpdateMyOrders
  ViewOthersQuoteRequests
  CreateOrdersFromOthersQuotes
  ViewMyOrders
  UpdateOthersQuoteRequests
}

input RemoveAssociateRolePermission {
  permission: Permission!
}

input SetAssociateRoleCustomField {
  name: String!
  value: String
}

input SetAssociateRoleCustomType {
  fields: [CustomFieldInput!]
  type: ResourceIdentifierInput
  typeKey: String
  typeId: String
}

input SetAssociateRoleName {
  name: String
}

input SetAssociateRolePermissions {
  permissions: [Permission!]
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetProjectSettingsMyBusinessUnitAssociateRoleOnCreation {
  associateRole: ResourceIdentifierInput
}