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 authentication 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 (space delimited list of roles being requested)

• Username

• Password

• Grant Type (set to password)

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

1POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
2Content-Type: application/x-www-form-urlencoded;
3
4	     
5client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=password&username=insert-user-name&password=insert-password&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 (space delimited list of roles being requested)

• Grant Type (set to client_credentials)

1POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
2Content-Type: application/x-www-form-urlencoded;
3
4client_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)

1POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
2Content-Type: application/x-www-form-urlencoded;
3
4client_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 password grant type workflow except with an additional requirement of client secret.

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

• ClientID

• Scope (space delimited list of roles being requested)

• Username

• Password

• ClientSecret (set on api client)

• Grant Type (set to password)

1POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
2Content-Type: application/x-www-form-urlencoded;
3
4client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=password&username=insert-user-name&password=insert-password&scope=Shopper&client_secret=xxxxxxxxxxxxx

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.

Error Handling

When managing authentication flows, error scenarios should be handled by your application to help guide users to resolution. To start, here's a sample error response:

1{
2	"error": "invalid_grant",
3	"error_description": "Password does not meet security requirements.",
4	"Errors": [
5        {
6            "ErrorCode": "PasswordReset.InsecurePassword",
7            "Message": "Password does not meet security requirements.",
8            "Data": {
9	        "MinimumCharacterCount": 10,
10                "UpperCaseRequired": true,
11                "SpecialCharacterRequired": true,
12                "NumericRequired": true
13            }
14        }
15    ]
16}

Multiple errors can be returned, but more than likely, you'll want to focus on programming to Errors[0].ErrorCode

Authentication Errors

When logging in via /oauth/token, the following error codes can be returned to drive user action. Recoverable means the end user is able to re-attempt login. For those errors which are not recoverable, you may have to have an administrator role fix the user before they can retry.

Password Reset Errors

For requests to reset the password /password/reset, the following errors can be returned as part of that workflow. In many cases, these errors will be driven by the setup of the security profile

Subsequent Requests

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

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

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:

1GET https://api.ordercloud.io/v1/buyers HTTP/1.1
2
3Authorization: Bearer eyJ0eXAi0iJKV1QiLCJhbGci0iJ9...
4Content-Type: application/json; charset=UTF-8

Token Revocation

Existing user tokens are revoked automatically when a user is deactivated or the user's password is reset. Additionally, a user's tokens can now be explicitly revoked through new endpoints for admin, buyer, and supplier users.

DELETE v1/adminusers/{userID}/tokens
DELETE v1/buyers/{buyerID}/users/{userID}/tokens
DELETE v1/suppliers/{supplierID}/users/{userID}/tokens

Additionally, a user can revoke their own tokens without needing an elevated role by calling DELETE v1/me/tokens, which is functionally equivalent to a "sign me out of all devices" feature.

Behind the scenes, token revocation can take up to 20 seconds to be reflected due to caching.

Conclusion

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

Still have questions?
Ask in our Community Channel

Content Powered By