Establishing API access

Now that you have accessed your Marketplace and gained access to the API Console, you can begin establishing API access for users within your Marketplace. There are two main API resources relevant to establishing API access:

• API Clients - API clients are access points to your Marketplace data. These access points have properties that control what parties can use it, how they can gain access, and for how long that access remains valid.
• Security Profiles - Security profiles are groups of roles (permissions), each of which grant users access to specific API endpoints and functionality. This lets you control access to your Marketplace at the API level. If a request is made by a user without sufficient roles, they receive a 403 Forbidden response.

Create a shared API client

Open the API Console. In the resources menu under AUTHENTICATION AND AUTHORIZAION, select API clients.

From the dropdown, select POST Create an API client. You are presented with a form that has many settings available. We will be configuring the simplest version of an API client to keep things simple. If you want to read more about API clients in detail, see our more in-depth articles.

See API clients for more information.

Choosing the right name for your API client is important. By picking something descriptive, future developers will better understand when they should use it. Call the new API client "Shared API Client" because it will be shared between all of the parties in your Marketplace.

Navigate to Client Access section and make the following changes:

We are leaving supplier access turned off because we will not be covering the concept of suppliers in this walkthrough. By selecting Allow Seller and Allow Any Buyer, we are saying that any admin user (seller) and any buyer user (shopper) can authenticate using this new API client. It is worth noting that this type of API configuration that allows both buyers and sellers is not very common. Usually buyers and sellers sign into different applications, so it makes more sense to create a separate API client for each. We are creating a shared API client here for simplicity.

Submit the form by clicking the Send button.

Create your first users

For this walkthrough, access the OrderCloud API from both the seller and buyer perspectives. Creating your first buyer user requires a few more steps because you must first establish a buyer organization.

Create an admin user

In the left-hand resource menu, select MARKETPLACE OWNER > Admin users. In the operation selector where it says GET List admin users, click to select the Create an admin user option.

This opens a form where you can fill in each field individually or paste a JSON object for the entire request body. Copy and paste the following into the JSON field:

{
  "ID": "ADMIN",
  "Username": "admin01",
  "Password": "INSERT_ADMIN_USER_PASSWORD",
  "FirstName": "Admin",
  "LastName": "User",
  "Email": "[email protected]",
  "Active": true
}

Note: A password must have a minimum length of 10 characters and contain at least one digit, one uppercase character, and one lowercase character. Replace Password with something you will remember and take note of it; you will need this later.

Click Send. The API response appears on the right-hand side.

Create your first buyer organization and user

In the left-hand resource menu, select BUYER > Buyers. In the operation selector where it says GET List buyers, click to select the Create a buyer option.

As with the last request, copy and paste the following into the JSON field and click Send:

{
  "ID": "BUYER_ORGANIZATION",
  "Name": "Example Buyer",
  "Active": true
}

Next, select BUYER > Users and choose Create a user.

Notice that there is a new Buyer ID section above the request body fields. Since you are creating a buyer user, you need to tell OrderCloud which buyer organization to create the user in. Type BUYER_ORGANIZATION as the ID you provided in the previous request.

Now copy and paste the following into the JSON field:

{
  "ID": "BUYER_USER",
  "Username": "buyer01",
  "Password": "INSERT_BUYER_USER_PASSWORD",
  "FirstName": "Buyer",
  "LastName": "User",
  "Email": "[email protected]",
  "Active": true
}

Note: A password must have a minimum length of 10 characters and contain at least one digit, one uppercase character, and one lowercase character. Replace Password with something you will remember and take note of it; you will need this later.

Click Send.

Define and assign security profiles

We now have two different users, one admin and one buyer. We will be using the admin user to create product catalogs and manage orders, and our buyer user to shop product catalogs and submit orders. This means we need to limit each user's available API roles differently by creating and assigning security profiles.

Warning: It is considered bad practice to grant the FullAccess role to any Security Profile. Users with this role can completely remove data essential to your OrderCloud solution by making direct API calls, even if they are not supported by your application.

See Security Profiles for more information.

Create two security profiles

Navigate to Authentication and Authorization > Security Profiles and choose Create a Security Profile from the operation selector.

Create the following security profiles:

{
  "ID": "ADMIN_PROFILE",
  "Name": "Admin User Profile",
  "Roles": [
    "MeAdmin",
    "PasswordReset",
    "BuyerReader",
    "OrderAdmin",
    "CatalogAdmin",
    "ProductAdmin",
    "ProductAssignmentAdmin",
    "PriceScheduleAdmin",
    "ShipmentAdmin"
  ]
}

{
  "ID": "BUYER_PROFILE",
  "Name": "Buyer User Profile",
  "Roles": [
    "MeAdmin",
    "PasswordReset",
    "Shopper"
  ]
}

Security profile assignment

We now have two different users and two different profiles; however, we have not defined any relationship between them. This is where assignments come into play. Staying in Authentication and Authorization > Security Profiles, choose "Create or update a security profile assignment" from the operation selector.

In general, it is a best practice to avoid assigning things directly to the user level, as this can result in cumbersome management experiences where every time a new user is created you have to create a new security profile assignment. Instead, assign the admin and buyer profiles to our seller and buyer organizations respectively.

To assign our Admin User Profile to the entire seller organization (which will only be inherited by the admin users), copy and paste the following into the request body JSON field and click Send:

{
  "SecurityProfileID": "ADMIN_PROFILE"
}

Now when you get a list of admin users, you will see the Admin User Profile roles appear in the user's AvailableRoles field.

To assign our Buyer User Profile to the entire buyer organization, copy and paste the following into the JSON field and click Send:

{
  "SecurityProfileID": "BUYER_PROFILE",
  "BuyerID": "BUYER_ORGANIZATION"
}

Similarly, when you list buyer users under BUYER_ORGANIZATION, you will see the Buyer User Profile roles appear in the user's AvailableRoles field.

If we were to make additional assignments to other security profiles, you would see a union merge of all of the roles in any security profiles directly or indirectly assigned to each user in AvailableRoles.

Conclusion

We covered quite a lot in this guide. Review everything we did to establish API access for our Admin and Buyer users:

1. Created a shared API client that can be used by both sellers (admin users) and all buyers.
2. Created our first admin user, buyer organization, and buyer user.
3. Learned why not to use the FullAccess API role and the risks involved.
4. Created an admin security profile with the roles needed for catalog/product/order management.
5. Created a buyer security profile with the roles needed for a typical shopping experience.
6. Understood why it is recommended to avoid user-specific assignments.
7. Assigned our admin security profile to the seller organization.
8. Assigned our buyer security profile to the buyer organization.

You have now created both a seller and buyer perspective with proper security profiles. In the next guide, you will learn how to authenticate as these users and make your first API requests.