Understanding Security Profiles
Published by Jeff Ilse on October 20, 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 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.
Roles
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.
Role | Effect on assigning the role to a user |
|---|---|
| allows the user to update the |
| allows the user to update the |
| allows a user to update the |
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
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.
Still have questions?
Ask in our Community Channel