Making your first request

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

Moving forward

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

We have 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, follow the instructions here to import our OpenAPI specification by link: https://api.ordercloud.io/v1/openapi/v3.

Otherwise, check out our resources section for using our SDKs.

See Developer Tools for more information.

Retrieving an access token

OrderCloud uses OAuth 2.0 for token-based authentication. 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 focus on the commonly used password workflow, where an end user provides their account credentials (username/password) to generate an access token.

In the following example, 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 is required for all OAuth workflows.

The base URL is determined by the selected region and environment of your Marketplace. Check the base URL by navigating to the Marketplace in the API console near the top right and replace it in the following snippets.

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 can 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, acquire an access_token using your buyer user's credentials and roles.