OrderCloud Environment / Permission Setup for API Calls with flow diagrams

While invoking the product list API from both asp.net core SDK and JavaScript SDK (refer my earlier blogs), I realised that the API Client must be setup with proper relationships and permissions. Else, the invocation failed with different errors based on the missing relationship/permission. In this blog post, although I cover the use case  for product browsing this setup should be similar for all API calls except the role assignment. I have interspersed the blog with flow diagrams to demonstrate the code flow and possible reason for failure.

Since I cover the use case for product browsing, I take the buyer/buyer user into account. So, in this case, the buyer user is the api client context user. You need to add the relevant user and permission based on your scenario.

- Create Market Place

- Create an API Client

- Create a Buyer

- Create a Buyer User  

- Create a Security Profile

- Create a Security Profile Assignment

- Assign Default Context User to API Client

Create Marketplace:

In OrderCloud Portal, create New Marketplace:

Just add the mandatory field, which is Marketplace Name:

Note: Based on the region, the api url domain will change. For instance, the api domain for Europe-West will look like:  https://westeurope-sandbox.ordercloud.io while for Australia East, will look like this: https://australiaeast-sandbox.ordercloud.io

New Marketplace created successfully with auto-generated id:

Next, Click API Console in the left bar to open the console for querying APIs:

Also, if you have multiple market places, ensure that the correct marketplace is selected as the context:

Note that you can add multiple tabs with the + button and switch the marketplace context for each tab!

Create an API Client

Next, an API Client is needed within the marketplace:

POST /apiclients

Create New API Client with unique name and in an enabled state:

Since we want to allow product browsing , enable the anonymous buyer option:

The request must look something like this:

{

  "AppName": "My Europe Client",

  "Active": true,

  "IsAnonBuyer": true,

  "AccessTokenDuration": 600

}

Click the Create the API Client button and a API Client Id is generated:

At this point, if you add the API Client Id to your code and access the API, you will get the invalid_grant error:

To attach the API Client to a default context user, a user must be created first

Before that, a buyer must be created:

POST Create a new buyer

POST /buyers

Ensure Active toggle is enabled.

Next, create a new buyer user for the buyer:

POST Create a new user

POST /buyers/{buyerID}/users

POST Response:

In case if you already assigned the context user to the API Client and, if you execute the code, you will get the forbidden error:

Create a new Security Profile:

POST  /securityprofiles

Ensure to choose the appropriate roles needed for the user(s). 

Next, link the API Client Id, User Id and Buyer Id:

POST Create or update a security profile assignment

POST securityprofiles/assignment

Back in the API Client, assign the buyer user as default context user and save changes:

Note: If the "Allow all Buyers" toggle is not selected, the list of buyer users will not populate.

Create a new Product from POST /products:

Also, ensure that the active toggle is enabled for the product else, use the PUT request:

One more scenario for forbidden error:

Security profile is assigned but improper roles in the security profile!

One of the most popular errors while accessing the API is invalid_client error and the cause for the error is wrong API base url and since the base url changes depending on the region, added the below section

How to find the API Url for your OrderCloud Sandbox?

Based on the region your sandbox is deployed, your api url could change. Since the base url is very important for API calls, here is how to find the API url for your sandbox instance.

Go to OrderCloud marketplace by adding your unique marketplace id:

https://portal.ordercloud.io/marketplaces/{marketplaceid}

Or, you can select your marketplace from the list of marketplaces:

Once you click the marketplace, your API Server for the sandbox is as highlighted below: 

So, your code must reflect the above url:

Else, the api call will throw an invalid_client error.