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.

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.

Password Grant-Type Workflow

1POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
2Content-Type: application/x-www-form-urlencoded;
3
4{
5    client_id: "INSERT_SHARED_API_CLIENT_ID",
6    grant_type: "password",
7    username: "admin01",
8    password: "INSERT_ADMIN_USER_PASSWORD",
9    scope: "CatalogAdmin BuyerReader MeAdmin InventoryAdmin PasswordReset OrderAdmin PriceScheduleAdmin ProductAdmin ProductAssignmentAdmin ShipmentAdmin",
10}

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

1GET https://sandboxapi.ordercloud.io/v1/me HTTP/1.1
2Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
3Content-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.

Still have questions?
Ask in our Community Channel