1. Authentication

Authentication

Access token overview

Access tokens provide API authorization and contain:

  • User identity information
  • Role-based permissions
  • Access scope definitions

These tokens enable the API to validate requests and determine appropriate access levels.

Authentication workflows

OrderCloud implements six authentication workflows based on OAuth2 and OpenID Connect standards:

  1. Password grant type
  2. Client credentials
  3. Anonymous shopping
  4. Token refresh
  5. Elevated password
  6. Single sign-on (OpenID Connect)

Password grant type workflow

Standard user authentication requiring:

  • ClientID
  • Scope (space-delimited role list)
  • Username
  • Password
  • Grant type: password

Note: Client secret required if defined on API client.

Example request:

http
POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

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

Client credentials workflow

Backend system authentication requiring:

  • ClientID
  • Client secret
  • Scope (space-delimited role list)
  • Grant type: client_credentials

Example request:

http
POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

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

Anonymous shopping workflow

Enables guest browsing and checkout. See anonymous shopping documentation for implementation details.

Refresh token workflow

Enables session extension without re-authentication:

  • Requires initial authentication
  • API client must set RefreshTokenDuration
  • Uses refresh token from initial authentication

Required parameters:

  • ClientID
  • Refresh token
  • Grant type: refresh_token

Example request:

http
POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

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

Elevated password workflow

Enhanced security implementation requiring:

  • ClientID
  • Scope (space-delimited role list)
  • Username
  • Password
  • Client secret
  • Grant type: password

Example request:

http
POST https://sandboxapi.ordercloud.io/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&grant_type=password&username=insert-user-name&password=insert-password&scope=Shopper&client_secret=xxxxxxxxxxxxx

Single sign-on workflow

OpenID Connect integration enabling:

  • Third-party authentication
  • Social login support
  • Enterprise SSO integration

See SSO implementation guide for details.

Error handling

Error response structure

Example error response:

json
{
  "error": "invalid_grant",
  "error_description": "Password does not meet security requirements.",
  "Errors": [
    {
      "ErrorCode": "PasswordReset.InsecurePassword",
      "Message": "Password does not meet security requirements.",
      "Data": {
        "MinimumCharacterCount": 10,
        "UpperCaseRequired": true,
        "SpecialCharacterRequired": true,
        "NumericRequired": true
      }
    }
  ]
}

Implementation note: Focus error handling on Errors[0].ErrorCode.

Authentication error codes

OAuth token endpoint errors:

ErrorCodeDescriptionRecoverable
Auth.InvalidUsernameOrPasswordInvalid credentialsRetry
Auth.UsernameAndPasswordRequiredMissing credentialsRetry
Auth.PasswordExpiredPassword expirationPassword Reset
Auth.InsecurePasswordSecurity requirements not metPassword Reset
Auth.InsufficientRoleUnauthorized role requestNo
Auth.SellerNotActiveInactive marketplaceNo
Auth.UserNotActiveIncomplete user setupNo
Auth.LockedOutMaximum attempts exceededNo

Password reset error codes

Password reset endpoint errors:

ErrorCodeDescriptionRecoverable
PasswordReset.CannotReusePasswordRecent password reuseRetry
PasswordReset.TooSoonToChangeChange frequency limitWait
PasswordReset.InvalidVerificationInvalid reset tokenNo
PasswordReset.LockedOutAccount lockedNo
PasswordReset.MissingOrInvalidClientIDInvalid clientNo
PasswordReset.MissingUsernameMissing usernameNo

Authentication response handling

Successful authentication returns:

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

API request authorization:

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

Token revocation

Token invalidation occurs:

  • Automatically on user deactivation
  • After password reset
  • Through explicit revocation endpoints

Revocation endpoints:

  • DELETE v1/adminusers/{userID}/tokens
  • DELETE v1/buyers/{buyerID}/users/{userID}/tokens
  • DELETE v1/suppliers/{supplierID}/users/{userID}/tokens
  • DELETE v1/me/tokens (self-revocation)

Note: Revocation takes up to 20 seconds due to caching.

If you have suggestions for improving this article, let us know!