1. Access control & security

Understanding security profiles

Security profiles are groups of roles (permissions) that grant users access to specific API endpoints and functionality. This API-level access control provides robust marketplace security. Users without sufficient roles receive a 403 Forbidden response.

Role types

Reader and Admin roles

Most roles fall into two categories:

Admin roles

  • Read and write access
  • Full resource management
  • Complete endpoint access

Reader roles

  • Read-only access
  • List and Get operations
  • No modification rights

Example: PromotionReader allows:

  • List promotions
  • Get promotion details
  • No create/update/delete

Shopper role

Special role providing:

  • /me endpoint read access
  • Order creation ability
  • Line item management
  • Payment processing
  • Minimum shopping permissions

Me roles

Personal data management:

  • Read access via Shopper role
  • Write access via specific roles
  • Example: MeCreditCardAdmin
    • Create personal cards
    • Edit card details
    • Delete saved cards

Override roles

Special permissions for sensitive properties:

RoleCapability
OverrideShippingUpdate order ShippingCost
OverrideTaxUpdate order TaxCost
OverrideUnitPriceUpdate line item UnitPrice

Custom roles

Application-specific permissions:

  • User-defined roles
  • No built-in API access
  • Token-based validation
  • Custom feature control

Example implementation:

javascript
// Custom role: RecurringOrderAdmin
// Front-end validation
if (token.includes('RecurringOrderAdmin')) {
  // Allow recurring order creation
}

Benefits:

  • Centralized permission management
  • Application-specific controls
  • Consistent security model
  • OrderCloud integration

Assignment levels

Profile assignment options

  • User level
  • User group level
  • Buyer level
  • Supplier level
  • Seller level

Multiple profiles

  • Roles combine across profiles
  • Union of all assigned roles
  • Cumulative permissions
  • Hierarchical inheritance

Implementation notes

Access control

  • API-level security
  • Granular permissions
  • Role-based access
  • 403 error handling

Permission management

  • Group related roles
  • Assign appropriate levels
  • Monitor access patterns
  • Regular review needed
If you have suggestions for improving this article, let us know!