Sitecore OrderCloud Documentation

docs

Portal Login

Making Your First Request

This guide assumes you have completed all of the steps in Establishing API Access, if you skipped ahead please go back now and follow along with that guide.

Moving Forward

Up until now you've been using the API Console to make requests. From now on you will be using some sort of client outside of the Portal, whether it be Postman or a simple script running in the browser.

We have some open source packages available to aid in the development process for Javascript and C# solutions. we will be providing examples in raw HTTP format as well as in our JS/TS and C# SDKs to help you learn OrderCloud in the language that best suits your needs.

If you want to use Postman you can follow the instructions here to import our Open API Specification by link: https://api.ordercloud.io/v1/openapi/v3.

Otherwise check out our resources section for using our SDKs.

FURTHER READING

Developer Tools

Retrieving an Access Token

OrderCloud uses OAuth 2.0 for token-based authentication. This means that each API request to OrderCloud requires a valid access token which can be acquired through a variety of OAuth workflows. For this walkthrough we will be focusing on the commonly used password workflow, where an end user provides their account credentials (username/password) to generate an access token.

In the example below we are retrieving, and in some examples also storing an access token using the ID of the API Client we created in the last guide. Notice that we are also requesting a certain "scope" or list of OrderCloud API roles that we think the user should have access to.

Note: If a ClientSecret is defined on the API Client, it will be required for all OAuth workflows

The base URL is determined by the selected region and environment when first creating your marketplace. Please check the base url by navigating to the market place in the api console near the top left and replace it in the following snippets.

static page image
Password Grant-Type Workflow
POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded;

{
    client_id: "INSERT_SHARED_API_CLIENT_ID",
    grant_type: "password",
    username: "admin01",
    password: "INSERT_ADMIN_USER_PASSWORD",
    scope: "CatalogAdmin BuyerReader MeAdmin InventoryAdmin PasswordReset OrderAdmin PriceScheduleAdmin ProductAdmin ProductAssignmentAdmin ShipmentAdmin",
}

If you request a scope that includes more API roles than the user is assigned under AvailableRoles you will not receive an error. Instead, the token will simply include whatever roles the user does have in the requested scope. This allows you to maintain a single all encompassing scope variable for your implementation and use it for any authentication request.

OrderCloud does not differentiate between incorrect username vs. incorrect password requests to avoid password enumeration. Here are the possible OrderCloud error codes for this particular request:

  • InvalidGrant - The requested API Client does not exist or is not available for the username provided. This error may also occur if you included a ClientSecret but did not provide it in the request.

  • InvalidCredentials - The provided credentials do not match any account on record for the provided client

Using the Access Token

Once you have successfully retrieved (and stored, if using one of our SDKs) an access_token, you will be able to use it in subsequent API requests like so:

Authenticating Subsequent API Requests
GET https://sandboxapi.ordercloud.io/v1/me HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

This particular request is made using the seller perspective. To change perspectives you will need to acquire an access_token using your buyer user's credentials and roles.


Was this page helpful? Give it a bravo!

Still have questions?
Ask in our Community Channel

Content Powered By
Sitecore Logo

© Copyright 2024, Sitecore OrderCloud®. All rights reserved.

Contact Us
Privacy Policy
Sitecore