Understanding OAuth Access Tokens

OAuth is an open standard for authorization. OAuth allows users to share their private resources stored on one site with another site without having to hand out their credentials, typically supplying username and password tokens instead. Each token grants access to a specific site for specific resources and for a defined duration. This allows a user to grant a third-party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data.

Digital River Connect APIs grant the following OAuth token types:

  • Limited Access Token—A limited access token only grants you access to the Shopper APIs that do not require a consumer context. This token allows you to send API requests against resources that are not shopper-protected. However, you are limited to non-protected resources. A limited access token is considered an authenticated token; however, it is not an authorized token that provides full access. 

  • Full Access Token—To access all the features of the Shopper APIs, you need to get an authorized token. A full access token is only granted when the shopper explicitly allows your application to access their personal data. The shopper is the only one who can grant this token. This is accomplished by sending the shopper to the Global Commerce (GC) platform for authentication. After a shopper identifies themselves and explicitly grants your application permission to access their protected resources, your application has access to the full API.

Valid Token Types

The OAuth specification defines the available application type as follows:

  • Public—Applications are incapable of maintaining the confidentiality of their credentials or securely authenticating by any other means. For example, a public application includes those executing on a device used by the resource owner, such as installed native applications. All calls use an HTTP Basic Authentication header, with the client ID (API key) as the username; the secret key is never used. 
  • Confidential—Applications are capable of maintaining the confidentiality of their credentials, or are otherwise capable of secure client authentication. An example of a confidential application includes a client implemented on a secure server. All calls are done with an HTTP Basic Authentication header, with the client ID (API key) as the username and the secret key as the password.

See Public Versus Confidential Application Flows for more information.

The following table indicates which token types allow access to a resource.

Legend: 

✓–A check mark indicates the token type provides access to a resource.

✗–A cross mark indicates the token type does not provide access to a resource.

*–If a method has token requirements that differ from the other methods within a resource, the method is explicitly listed in the table. 


Resource
Method
Access Carts with API Key Only
Token Optional
Limited Access Token
Full Access Token
shoppers (client maintains login credentials)
POST




shoppers (Digital River maintains login credentials)
POST




shoppers/me
GET




shoppers/me
POST




shoppers/me/account
GET




shoppers/me/addresses
GET




shoppers/me/addresses
POST (CREATE or UPDATE)




shoppers/me/addresses/{id}
DELETE




shoppers/me/addresses/{id}
GET




shoppers/me/carts/active
GET




shoppers/me/carts/active
POST




shoppers/me/carts/active/apply-billing-address
POST




shoppers/me/carts/active/apply-payment-method
POST




shoppers/me/carts/active/apply-shipping-address
POST




shoppers/me/carts/active/apply-shipping-option
POST




shoppers/me/carts/active/apply-shopper
POST




shoppers/me/carts/active/billing-address

GET




shoppers/me/carts/active/billing-address
PUT




shoppers/me/carts/active/billing-address/suggestions
GET




shoppers/me/carts/active/billing-address/suggestions/{id}
GET




shoppers/me/carts/active/line-items
DELETE




shoppers/me/carts/active/line-items
GET




shoppers/me/carts/active/line-items
POST




shopper/me/carts/active/line-items/{id}
DELETE




shoppers/me/carts/active/line-items/{id}
GET




shoppers/me/carts/active/line-items/{id}
POST




shoppers/me/carts/active/payment-methods
GET




shoppers/me/carts/active/point-of-promotions
GET




shoppers/me/carts/active/point-of-promotions/{popName}

GET




shoppers/me/carts/active/point-of-promotions/{popName}/offers
GET




shoppers/me/carts/active/shipping-address
GET




shoppers/me/carts/active/shipping-address
PUT




shoppers/me/carts/active/shipping-address/suggestions
GET




shoppers/me/carts/active/shipping-address/suggestions/{id}
GET




shoppers/me/carts/active/shipping-options
GET




shoppers/me/cart/active/shipping-opionts/{id}
GET




shoppers/me/carts/active/submit-cart
POST




shoppers/me/carts/active/web-checkout
GET




shoppers/me/carts/active/web-checkout
POST




shoppers/me/categories
GET




shoppers/me/categories/{id}
GET




shoppers/me/categories/{id}/products
GET




shoppers/me/offers/{id}
GET




shoppers/me/offers/{id}/category-offers
GET




shoppers/me/offers/{id}/product-offers
GET




shoppers/me/offers/{id}/product-offers/{id}
GET




shoppers/me/orders

GET




shoppers/me/orders/{id}

GET




shoppers/me/orders/{id}/billing-address

GET




shoppers/me/orders/{id}/line-items
GET




shoppers/me/orders/{id}/line-items/{id}

GET




shoppers/me/orders/{id}/returns

GET




shoppers/me/orders/{id}/returns
POST




shoppers/me/orders/{id}/shipping-address
GET




shoppers/me/payment-options
GET




shoppers/me/payment-options/{id}
GET




shoppers/me/point-of-promotions
GET




shoppers/me/point-of-promotions/{popName}
GET




shoppers/me/point-of-promotions/{popName}/offers
GET




shoppers/me/products
GET




shoppers/me/products/inventory-status
GET




shoppers/me/products/{id}

GET




shoppers/me/products/{id}/categories
GET




shoppers/me/products/{id}/financing
GET




shoppers/me/products/{id}/inventory-status
GET




shoppers/me/products/{id}/point-of-promotions
GET




shoppers/me/products/{id}/point-of-promotions/{popName}
GET




shoppers/me/products/{id}/point-of-promotions/{popName}/offers
GET




shoppers/me/products/{id}/pricing
GET




shoppers/me/products/{id}/pricing/volume-pricing
GET




shoppers/me/products/{id}/purchase
POST




shoppers/me/products/{id}/variations
GET




shoppers/me/purchase-plan
GET




shoppers/me/purchase-plan/authorize
POST




shoppers/me/purchase-plan/search
GET




shoppers/me/subscriptions
GET




shoppers/me/subscriptions/{id}
GET




shoppers/me/wish-lists
DELETE




shoppers/me/wish-lists
GET




shoppers/me/wish-lists (creates shopper wish list)
POST




shoppers/me/wish-lists (updates or adds products to a wish list)
POST




shoppers/me/wish-lists/{id}
GET




shoppers/me/wish-lists/default
GET




shoppers/order-lookup
POST




shoppers/site
GET




shoppers/token
GET




site/settings
GET




Access Token TTL

The access token time-to-live (TTL) limits the lifespan of the access token. When using TTL, consider the following:

  • The default value is 24 hours.
  • By default, tokens remain valid for the same duration as Digital River-hosted storefront pages.

The expires_in property is the TTL value for the access token. An application can store a valid access token and re-use it until it expires.