Edit this doc

Authentication

Understanding Access Tokens

Access tokens are what gives you access to parts of the API and must be appended to every request. Encrypted in the token are the identity of the user as well as the roles that the user has access to. Once validated, the OrderCloud API has enough information from this token to determine which endpoints and data a user can read and/or write.

OrderCloud Workflows

OrderCloud's authentication system is built on top of an open authorization standard called OAuth2 which is increasingly becoming an industry standard for security and permission-based application experiences. OAuth2 provides five different workflows (ways of getting an access token). Additionally, OrderCloud has support for OpenID connect which is an authorization standard built on top of OAuth2 which enables single-sign-on and brings our grand tally up to 6 workflows.

Password Grant Type Workflow

This is the most common, a user logs in with their username and password.

A successful authentication request with this workflow requires the following information:

  • ClientID
  • Scope (list of roles being requested)
  • Username
  • Password
  • Grant Type (set to password)
POST https://auth.ordercloud.io/oauth/token HTTP/1.1
Content-Type: text/html; charset=UTF-8

client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=password&username=xxxxxxxx&password=xxxxxxxx&scope=Shopper

Client Credentials Workflow

This is typically used by a backend integration system.

A successful authentication request with this workflow requires the following information:

  • ClientID
  • Client Secret
  • Scope (list of roles being requested)
  • Grant Type (set to client_credentials)
POST https://auth.ordercloud.io/oauth/token HTTP/1.1
Content-Type: text/html; charset=UTF-8

client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=client_credentials&client_secret=xxxxxxxxxxxxx&scope=Shopper

Anonymous Shopping or Guest Checkout Workflow

You may want to enable visitors to browse a catalog of products and/or checkout without registering themselves. We call this Anonymous Shopping or Guest Checkout. An in-depth guide for this workflow is detailed here

Refresh Workflow

Securely enable your users to obtain a new access token without having to log in again.

This workflow is a bit different than the rest in that it can only be used once a token has initially been requested using one of the other workflows. Additionally it must be enabled in the API by setting ApiClient.RefreshTokenDuration to a number greater than 0. Once that is set, your authentication responses will include a refresh_token that you can use to extend the lease on your user's session.

A successful authentication request with this workflow requires the following information:

  • ClientID
  • Refresh Token (from a successful authentication response using any of the other auth workflows)
  • Grant Type (set to refresh_token)
POST https://auth.ordercloud.io/oauth/token HTTP/1.1
Content-Type: text/html; charset=UTF-8

client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=refresh_token&refresh_token=xxxxxxxx-xxxxxxxx-xxxx-xxxxxxx&scope=Shopper

Elevated Password Flow

When security really matters. This is the same as the

except with an additional requirement of client secret.

A successful authentication request with this workflow requires the following information:

  • ClientID
  • Scope (list of roles being requested)
  • Username
  • Password
  • ClientSecret (set on api client)
  • Grant Type (set to password)
POST https://auth.ordercloud.io/oauth/token HTTP/1.1
Content-Type: text/html; charset=UTF-8

client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=client_credentials&client_secret=xxxxxxxxxxxxx&scope=Shopper

Single Sign on Flow via OpenID Connect

Powered by OpenID Connect, Single Sign on allows your users to authenticate themselves to the OrderCloud API by logging into any other identity provider you trust. For example, let shoppers save addresses and orders on your site by logging in with Google or Facebook. Or, save your users the hassle of one more login screen by providing a single sign-on point through your system. Check out our in-depth guide for more details.

Subsequent Requests

A successful authentication (using one of the four workflows) will yield the following response:

{
  "access_token": "eyJ0eXAi0iJKV1QiLCJhbGci0iJ9...",
  "token_type": "bearer",
  "expires_in": 35999,
  "refresh_token": "878ca890-af6a-48b6-98a2-1e1cf4a.."
}

The access_token from the response will need to be included in each and every api request as part of the Authorization header prefaced with Bearer

For example:

GET https://api.ordercloud.io/v1/buyers HTTP/1.1

Authentication: Bearer eyJ0eXAi0iJKV1QiLCJhbGci0iJ9...
Content-Type: application/json; charset=UTF-8

Conclusion

As you can see there are many different ways that you can obtain an access token to give someone access to your organization but what about limiting access within your organization? OrderCloud has a built-in way of handling access within your organization via Security Profiles which we'll talk about next.