Understanding Security Profiles

Security profiles are groups of roles (permissions), each of which grant users access to specific API endpoints and functionality. This lets you lock down access to your marketplace at the API level which is very powerful. If a request is made by a user without sufficient roles, they will receive a 403 Forbidden response.

Most OrderCloud roles fall into one of two categories: Admin and Reader. An Admin role allows read and write access to a resource while a Reader role allows only read access.

For example, a user that is assigned a security profile that has the role PromotionReader will be able to List, or Get Promotions but will not be able to modify a promotion by calling Create, Patch, Save, or Delete endpoints.

This special role grants a user read access to all of the /me endpoints as well as the ability to create an order, lineitems, and payments. In short, it provides the minimum set of access a user needs to be able to “shop”. If your needs are simple enough, this may be the only role you need to assign your buyer user!

During the normal shopping flow, users with the Shopper role can create and modify their own unsubmitted order and its related line items.

Once an order has been submitted or approved, modifying the order becomes a privileged operation. This includes changes to the order itself as well as creating, updating, or deleting line items on the order.

Buyer users can be granted the OrderEditAfterSubmit role to modify their own submitted or approved orders. This role does not allow a buyer user to modify another user’s orders.

When possible, post-submit order changes should be performed by a trusted application or integration using administrative permissions rather than granting OrderEditAfterSubmit directly to buyer users. If buyer users must be able to modify submitted orders, assign OrderEditAfterSubmit only to the specific users who require that capability rather than including it in a broadly assigned security profile.

For user types or scenarios that require modifying submitted or approved orders beyond the caller’s own orders, OrderAdmin or FullAccess is required.

Users without the required role will receive a 403 Forbidden response when attempting these operations.

The Shopper role enables read access to the /me endpoints however there are various permissions that define write access to their own data. For example a user with MeCreditCardAdmin would allow that user to create/edit/delete any of their own personal credit cards.

Some properties in OrderCloud’s data model have been deemed important enough to require a special role in addition to the Admin role for the resource.

Custom roles let you lock down access to your app’s custom features using OrderCloud’s security profiles.

These roles are simple string values that will appear on your users’ authentication tokens like normal roles. Unlike normal roles, they do not grant access to any API functionality. Instead, use them to control access to your app-specific features. For example, you might want to give some users the ability to place recurring orders (a feature OrderCloud could support, but which has no pre-existing role). You would add a RecurringOrderAdmin custom role to a security profile and in your front-end code check that the token contains this string before you let users place a recurring order.

Custom roles mean that all your user permission data can live in OrderCloud.

OrderCloud Security profiles can be assigned at any of the following levels: user, user group, buyer, supplier, or seller level.

If your user is assigned more than one security profile, the roles given to that user will be a union of the roles from every assigned security profile.