Understanding Security Profiles

Suggest an edit
Jeff Ilse

Published by Jeff Ilse

October 20th, 2016

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 organization 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.


Reader and Admin Roles

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.

Shopper Role

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!

Me Roles

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.

Override Roles

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.

RoleEffect on assigning the role to a user
OverrideShippingallows a user to update the ShippingCost on an order
OverrideTaxallows a user to update the TaxCost on an order
OverrideUnitPriceallows a user to update the UnitPrice on a line item

Custom Roles

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.

Assigning Security Profiles

Like most things in 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.