---
title: Authentication overview
slug: authentication
abstract: Access tokens provide API authorization and contain
content_type: concept
audience: \[developer, architect]
---
# Authentication overview

## 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](https://doc.sitecore.com/ordercloud/en/developers/platform/anonymous-shopping.html) 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 the [SSO implementation guide](https://doc.sitecore.com/ordercloud/en/developers/platform/single-sign-on.html) 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:

| ErrorCode | Description | Recoverable |
| ----------- | ------------- | ------------- |
| `Auth.InvalidUsernameOrPassword` | Invalid credentials | Retry |
| `Auth.UsernameAndPasswordRequired` | Missing credentials | Retry |
| `Auth.PasswordExpired` | Password expiration | Password Reset |
| `Auth.InsecurePassword` | Security requirements not met | Password Reset |
| `Auth.InsufficientRole` | Unauthorized role request | No |
| `Auth.SellerNotActive` | Inactive marketplace | No |
| `Auth.UserNotActive` | Incomplete user setup | No |
| `Auth.LockedOut` | Maximum attempts exceeded | No |

### Password reset error codes

Password reset endpoint errors:

| ErrorCode | Description | Recoverable |
| ----------- | ------------- | ------------- |
| `PasswordReset.CannotReusePassword` | Recent password reuse | Retry |
| `PasswordReset.TooSoonToChange` | Change frequency limit | Wait |
| `PasswordReset.InvalidVerification` | Invalid reset token | No |
| `PasswordReset.LockedOut` | Account locked | No |
| `PasswordReset.MissingOrInvalidClientID` | Invalid client | No |
| `PasswordReset.MissingUsername` | Missing username | No |

## 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.

## Related reading

- [Order fees](https://doc.sitecore.com/ordercloud/en/developers/platform/orders.html#order-fees)
- [OrderCloud accelerator](https://doc.sitecore.com/ordercloud/en/developers/platform/accelerator.html)
- [Bundle products for enhanced commerce experiences](https://doc.sitecore.com/ordercloud/en/developers/platform/product-bundles.html#bundle-products-for-enhanced-commerce-experiences)