1. Configuration

Configuring user and application data access

Implementation requirements

Prerequisites

  • Sandbox marketplace access or existing marketplace
  • Active users:
    • Buyer user: ID/Username buyeruser, Password "Supersecurepassword123!"
    • Seller user: ID/Username selleruser, Password "Supersecurepassword123!"
  • Active buyer company: ID buyercompany
  • Example ClientIDs:
    • Buyer storefront: "00000000-0000-0000-0000-000000000000"
    • Admin backoffice: "11111111-1111-1111-1111-111111111111"
    • Middleware API: "222222222-2222-2222-2222-222222222222"
    • Middleware Secret: "supersecureclientsecretstring"

API client configuration

API clients control application access to marketplace data. Best practice: Use separate clients for each application.

Create buyer storefront client

http
POST sandboxapi.ordercloud.io/v1/apiclients HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "AppName": "Buyer Storefront",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnyBuyer": true
}

JavaScript:

javascript
import { ApiClients } from "ordercloud-javascript-sdk";

ApiClients.Create({
  "AppName": "Buyer Storefront",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnyBuyer": true
})
.then((apiClient) => {
  console.log(apiClient);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { ApiClients, ApiClient, OrderCloudError } from "ordercloud-javascript-sdk";

ApiClients.Create({
  "AppName": "Buyer Storefront",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnyBuyer": true
})
.then((apiClient: ApiClient) => {
  console.log(apiClient);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new ApiClient
{
  "AppName": "Buyer Storefront",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnyBuyer": true
};

try {
  ApiClient response = await ApiClients.Create(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Create admin backoffice client

http
POST https://sandboxapi.ordercloud.io/v1/apiclients HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "AppName": "Admin Backoffice",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "AllowAnySupplier": true
}

JavaScript:

javascript
import { ApiClients } from "ordercloud-javascript-sdk";

ApiClients.Create({
  "AppName": "Admin Backoffice",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "AllowAnySupplier": true
})
.then((apiClient) => {
  console.log(apiClient);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { ApiClients, ApiClient, OrderCloudError } from "ordercloud-javascript-sdk";

ApiClients.Create({
  "AppName": "Admin Backoffice",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "AllowAnySupplier": true
})
.then((apiClient: ApiClient) => {
  console.log(apiClient);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new ApiClient
{
  "AppName": "Admin Backoffice",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "AllowAnySupplier": true
};

try {
  ApiClient response = await ApiClients.Create(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Create middleware API client

http
POST https://sandboxapi.ordercloud.io/v1/apiclients HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "AppName": "Middleware API",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "ClientSecret": "supersecureclientsecretstring"
}

JavaScript:

javascript
import { ApiClients } from "ordercloud-javascript-sdk";

ApiClients.Create({
  "AppName": "Middleware API",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "ClientSecret": "supersecureclientsecretstring"
})
.then((apiClient) => {
  console.log(apiClient);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { ApiClients, ApiClient, OrderCloudError } from "ordercloud-javascript-sdk";

ApiClients.Create({
  "AppName": "Middleware API",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "ClientSecret": "supersecureclientsecretstring"
})
.then((apiClient: ApiClient) => {
  console.log(apiClient);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new ApiClient
{
  "AppName": "Middleware API",
  "Active": true,
  "AccessTokenDuration": 600,
  "AllowAnySeller": true,
  "ClientSecret": "supersecureclientsecretstring"
};

try {
  ApiClient response = await ApiClients.Create(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Security profile configuration

Security profiles define granular data access for individual users.

Create buyer profile

http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "ID": "defaultbuyer",
  "Name": "Default Buyer",
  "Roles": [
    "Shopper"
  ]
}

JavaScript:

javascript
import { SecurityProfiles } from "ordercloud-javascript-sdk";

SecurityProfiles.Create({
  "ID": "defaultbuyer",
  "Name": "Default Buyer",
  "Roles": [
    "Shopper"
  ]
})
.then((securityProfile) => {
  console.log(securityProfile);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { SecurityProfiles, SecurityProfile, OrderCloudError } from "ordercloud-javascript-sdk";

SecurityProfiles.Create({
  "ID": "defaultbuyer",
  "Name": "Default Buyer",
  "Roles": [
    "Shopper"
  ]
})
.then((securityProfile: SecurityProfile) => {
  console.log(securityProfile);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new SecurityProfile
{
  "ID": "defaultbuyer",
  "Name": "Default Buyer",
  "Roles": new ApiRole[] { ApiRole.Shopper }
};

try {
  SecurityProfile response = await SecurityProfiles.Create(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Create seller profile

http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "ID": "defaultseller",
  "Name": "Default Seller",
  "Roles": [
    "BuyerAdmin",
    "ProductAdmin",
    "OrderAdmin"
  ]
}

JavaScript:

javascript
import { SecurityProfiles } from "ordercloud-javascript-sdk";

SecurityProfiles.Create({
  "ID": "defaultseller",
  "Name": "Default Seller",
  "Roles": [
    "BuyerAdmin",
    "ProductAdmin",
    "OrderAdmin"
  ]
})
.then((securityProfile) => {
  console.log(securityProfile);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { SecurityProfiles, SecurityProfile, OrderCloudError } from "ordercloud-javascript-sdk";

SecurityProfiles.Create({
  "ID": "defaultseller",
  "Name": "Default Seller",
  "Roles": [
    "BuyerAdmin",
    "ProductAdmin",
    "OrderAdmin"
  ]
})
.then((securityProfile: SecurityProfile) => {
  console.log(securityProfile);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new SecurityProfile
{
  "ID": "defaultseller",
  "Name": "Default Seller",
  "Roles": new ApiRole[] { ApiRole.BuyerAdmin, ApiRole.ProductAdmin, ApiRole.OrderAdmin }
};

try {
  SecurityProfile response = await SecurityProfiles.Create(data);
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Profile assignment implementation

Assign buyer profile

http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles/assignments HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "SecurityProfileID": "defaultbuyer",
  "BuyerID": "buyercompany"
}

JavaScript:

javascript
import { SecurityProfiles } from "ordercloud-javascript-sdk";

SecurityProfiles.SaveAssignment({
  "SecurityProfileID": "defaultbuyer",
  "BuyerID": "buyercompany"
})
.then(() => {
  console.log("Assignment successful!");
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { SecurityProfiles, SecurityProfile, OrderCloudError } from "ordercloud-javascript-sdk";

SecurityProfiles.SaveAssignment({
  "SecurityProfileID": "defaultbuyer",
  "BuyerID": "buyercompany"
})
.then(() => {
  console.log("Assignment successful!");
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new SecurityProfileAssignment
{
  "SecurityProfileID": "defaultbuyer",
  "BuyerID": "buyercompany"
};

try {
  await SecurityProfiles.SaveAssignment(data);
  Console.WriteLine("Assignment successful!");
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Assign seller profile

http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles/assignments HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "SecurityProfileID": "defaultseller"
}

JavaScript:

javascript
import { SecurityProfiles } from "ordercloud-javascript-sdk";

SecurityProfiles.SaveAssignment({
  "SecurityProfileID": "defaultseller"
})
.then(() => {
  console.log("Assignment successful!");
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { SecurityProfiles, SecurityProfile, OrderCloudError } from "ordercloud-javascript-sdk";

SecurityProfiles.SaveAssignment({
  "SecurityProfileID": "defaultseller"
})
.then(() => {
  console.log("Assignment successful!");
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

var data = new SecurityProfileAssignment
{
  "SecurityProfileID": "defaultseller"
};

try {
  await SecurityProfiles.SaveAssignment(data);
  Console.WriteLine("Assignment successful!");
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Authentication implementation

Buyer authentication

http
POST https://sandboxapi.ordercloud.io/v1/outh/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=00000000-0000-0000-0000-000000000000&grant_type=password&username=buyeruser&password=Supersecurepassword123!&scope=Shopper

JavaScript:

javascript
import { Auth } from "ordercloud-javascript-sdk";

Auth.Login("defaultbuyer", "Supersecurepassword123!", "00000000-0000-0000-0000-000000000000", ["Shopper"])
.then((authResponse) => {
  console.log(authResponse.access_token);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { Auth, AccessToken, OrderCloudError } from "ordercloud-javascript-sdk";

Auth.Login("defaultbuyer", "Supersecurepassword123!", "00000000-0000-0000-0000-000000000000", ["Shopper"])
.then((authResponse: AccessToken) => {
  console.log(authResponse.access_token);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

try {
  AccessToken response = await ocClient.AuthenticateAsync("00000000-0000-0000-0000-000000000000", "defaultbuyer", "Supersecurepassword123!", new ApiRole[] { ApiRole.Shopper });
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Seller authentication

http
POST https://sandboxapi.ordercloud.io/v1/outh/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=11111111-1111-1111-1111-111111111111&grant_type=password&username=selleruser&password=Supersecurepassword123!&scope=FullAccess

JavaScript:

javascript
import { Auth } from "ordercloud-javascript-sdk";

Auth.Login("selleruser", "Supersecurepassword123!", "11111111-1111-1111-1111-111111111111", ["FullAccess"])
.then((authResponse) => {
  console.log(authResponse.access_token);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { Auth, AccessToken, OrderCloudError } from "ordercloud-javascript-sdk";

Auth.Login("selleruser", "Supersecurepassword123!", "11111111-1111-1111-1111-111111111111", ["FullAccess"])
.then((authResponse: AccessToken) => {
  console.log(authResponse.access_token);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

try {
  AccessToken response = await ocClient.AuthenticateAsync("11111111-1111-1111-1111-111111111111", "selleruser", "Supersecurepassword123!", new ApiRole[] { ApiRole.FullAccess });
  Console.WriteLine(response);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Client credentials authentication

http
POST https://sandboxapi.ordercloud.io/v1/outh/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=222222222-2222-2222-2222-222222222222&grant_type=client_credentials&client_secret=supersecureclientsecretstring&scope=FullAccess

JavaScript:

javascript
import { Auth } from "ordercloud-javascript-sdk";

Auth.ClientCredentials("supersecureclientsecret", "222222222-2222-2222-2222-222222222222", ["FullAccess"])
.then((token) => {
  console.log(token);
})
.catch((ex) => console.log(ex));

TypeScript:

typescript
import { Auth, AccessToken, OrderCloudError } from "ordercloud-javascript-sdk";

Auth.ClientCredentials("supersecureclientsecret", "222222222-2222-2222-2222-222222222222", ["FullAccess"])
.then((token: AccessToken) => {
  console.log(token);
})
.catch((ex: OrderCloudError) => console.log(ex));

C#:

csharp
using OrderCloud.SDK;

try {
  AccessToken token = await ocClient.AuthenticateAsync("222222222-2222-2222-2222-222222222222", "supersecureclientsecret", new ApiRole[] { ApiRole.FullAccess });
  Console.WriteLine(token);
} catch(OrderCloudException ex) {
  Console.WriteLine(ex.Message);
}

Implementation considerations

This implementation demonstrates one approach to API client and security profile configuration. The platform supports various configurations to meet specific business requirements. Key points:

  1. API client management:

    • Separate clients per application
    • Appropriate access levels
    • Security considerations

  2. Security profile design:

    • Granular role assignment
    • User type separation
    • Access control hierarchy

  3. Authentication patterns:

    • User-based authentication
    • System authentication
    • Token management
If you have suggestions for improving this article, let us know!