1. Authentication and security

Security profiles and roles

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

Why you should never use FullAccess

In security, the Principle of Least Privilege states "that a security architecture should be designed so that each entity is granted the minimum system resources and authorizations that the entity needs to perform its function". Therefore, best practices dictate that it's better to never use FullAccess at all than to allow it to become a bad habit and risk giving users access to your application and data in ways you never intended.

Understanding FullAccess

FullAccess is a Role that can be assigned to an organization, group, or user via SecurityProfile. This role grants complete access to the OrderCloud API, making it a powerful but potentially dangerous permission level.

Security risks

A user with FullAccess can make any call to the OrderCloud API. Here are just a few examples of detrimental actions a user with FullAccess could take against your organization:

  • Delete all products, orders, users, etc.
  • Change pricing on every product in your catalog
  • Mine all user data including email addresses and other personally identifiable information
  • Change any user's password, which would then allow them to login as that user

Certain users are prohibited from administering some resources regardless of what roles are assigned to them. For example, a buyer user cannot administer things like ApiClients or Webhooks, even if they are granted the ApiClientAdmin or WebhookAdmin, or FullAccess roles.

Design considerations

The reasoning behind providing a FullAccess role was that it would be a useful tool for developers to use in a pinch for short term testing. It could save them the few minutes of time it would take to figure out what explicit roles a user would need to perform a specific action.

However, we have observed instances where the role is being assigned widely to many users, which indicates that FullAccess is likely being used in scenarios beyond just testing or development tasks.

Recommendations:

  • Use specific roles tailored to each user's needs
  • Define clear boundaries for access permissions
  • Regularly review and audit user permissions
  • Remove any unnecessary access rights
  • Consider FullAccess only for temporary development testing

We hope you'll take this guidance into consideration while building and maintaining your OrderCloud applications.

If you have suggestions for improving this article, let us know!