OAuth 2.0 APIs

Understand OAuth 2.0 APIs.

OAuth 2.0 allows users to share data with applications while keeping their passwords and other information private. It assigns user authentication to the service that hosts the user account and authorizes third-party applications to access it. Using OAuth 2.0, applications can ask for access tokens from an authorization server, use them to authenticate API requests, and securely manage user permissions without having to handle user credentials directly.

How Digital River uses OAuth 2.0 with Commerce APIs

Digital River employs OAuth 2.0 to authenticate and authorize its Commerce APIs. It allows third-party applications to securely perform actions on a shopper's behalf without needing to access the shopper's password.

OAuth 2.0 enables applications to:

Request access tokens from the authorization server.
Authenticate API requests using these tokens.
Manage user permissions securely.

Public resources do not require an access token but use an API key configured as a public key. You can implement various OAuth workflows using these endpoints:

/oauth20/token
/oauth20/authorize

Anonymous shopper token

An anonymous shopper token is a type of token that grants limited access to specific resources before authenticating a shopper. You can obtain this token by sending a request to the /oauth20/token endpoint with your API key as a query parameter.

While the anonymous shopper token authenticates a request, it does not carry authorization for all shopper-specific actions. You can use this token to access public resources or perform tasks that do not require full shopper authentication. For broader access and shopper-specific interactions, transitioning to an authenticated shopper token through the /oauth20/authorize endpoint is necessary. For more information, see the Creating an anonymous shopper session (guest checkout) section.

Authenticated shopper token

An authenticated shopper token provides full access to shopper-specific resources and actions within the application. This token is obtained by sending a request to the /oauth20/authorize endpoint with the necessary parameters, including the API key and redirect URI. Once the shopper successfully authenticates, the system redirects them to your application with the authenticated shopper token. You can use this token for any operations that require access to shopper-specific data and functionalities, ensuring secure and personalized interactions for authenticated users. For more information, see the Initiating an authenticated session (returning shopper or login shopper) section.

OAuth access token

OAuth is an open standard for authorization. OAuth allows users to share their confidential resources stored on one site with another site without submitting their user credentials. Each token grants access to a specific site for specific resources and a defined duration. It allows a user to grant third-party site access to the information they provided to another service provider without sharing their access permissions or the full extent of their data.

Digital River Connect APIs grant anonymous and authenticated shopper tokens.

Valid token types

Tokens are crucial in the OAuth 2.0 framework, facilitating secure and seamless communication between clients and servers. They serve as digital proof of authorization, allowing clients to access protected resources without exposing sensitive credentials. There are different types of tokens, each designed with specific purposes and security measures in mind. Below are the primary token types defined by the OAuth specification:

Bearer tokens: Use them for token-based authentication and pass them with each HTTP request. Possessing a bearer token grants access to the associated resources.
Refresh tokens: Use them to obtain a new access token when the current one becomes invalid or expires. Refresh tokens enhance security and user experience by allowing long-term access without repeatedly asking for credentials.

Access token TTL

Access tokens are vital in ensuring secure communication within the OAuth 2.0 framework. However, to maintain security and control, limiting their lifespan is essential. The access token time-to-live (TTL) parameter specifies how long an access token remains valid, reducing the risk of unauthorized access if a token is compromised. This section details the default TTL settings and considerations for using TTL in your applications.

The TTL limits the lifespan of the access token in seconds. When using TTL, consider the following:

The default value is 24 hours (86397 seconds)
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 reuse it until it expires.

Public versus confidential authentication flows

OAuth 2.0 has two primary types of authentication flows: public and confidential. Understanding the differences between these flows is crucial for implementing the appropriate security measures based on your application's needs. Public flows are designed for scenarios where someone might expose the credentials, whereas confidential flows ensure credentials are kept secure and confidential.

Public flow

Use the public flow when you want to obfuscate, but make your API key and OAuth tokens accessible to the public with some technical effort. This flow is suitable when replay attacks are unlikely within the token's lifespan, and the API keys and tokens are obfuscated, such as behind a decompiler.

Confidential flow

A confidential flow is a secure OAuth 2.0 authentication process where sensitive credentials, such as API keys and tokens, are kept completely hidden from public exposure. The process typically includes a server proxy to ensure these credentials remain secure between the application and the Digital River servers.

OAuth flows allowed by grant and client types

OAuth 2.0 supports various flows depending on the grant type and the type of client application. Each flow specifies how an application interacts with the authorization server to obtain tokens and whether it supports refresh tokens. The following table outlines the OAuth flows allowed based on grant type and client type, including their support for refresh tokens.