Token

Learn how to create authenticated shopper tokens.

Use the /oauth20/token resource with client credentials (grant_type=password) to generate either an anonymous or authenticated shopper token. The API requirements depend on the type of application that invokes a request. A shopper can anonymously use a guest checkout token when shopping for a product. You need an authenticated shopper token to retrieve authenticated shopper-specific details, such as address or payment details. This token only supports a public workflow.

The /oauth20/token resource generates an access token that you can use to access resources. You can also use it to refresh an access token.

It is of utmost importance that you do not show or reveal the access tokens (limited or full) generated by APIs to the shopper in any visible way. It includes situations like storing them in plain text in a cookie. If a shopper gains access to these tokens, they could bypass any restrictions we have implemented on the storefront and place orders directly on our systems using the APIs that we have made publicly available. Your vigilance in this matter is crucial for maintaining the security of our eCommerce system.

Creating an anonymous shopper session (guest checkout)

An anonymous shopper token allows a shopper to access the Commerce APIs that do not require a consumer context. This token allows the shopper to send API requests against non-shopper-protected resources. An anonymous shopper token is an authenticated token. However, it is not an authorized token that provides full access.

To create an anonymous shopper token for a public or confidential application when the shopper wants to shop anonymously, use the POST /oauth20/token. When you create an anonymous shopper token for an application using client credentials, include your base64-encoded API key and secret in the request header.

cURL

curl --location --request POST 
'https://api.digitalriver.com/oauth20/token?grant_type=password' \
--header 'authorization: bearer ***\
...

200 OK response

{  
    "access_token": "your_access_token",  
    "token_type": "bearer",  
    "expires_in": "3599",  
    "refresh_token": "your_refresh_token"
}

Initiating an authenticated session (returning shopper or login shopper)

An authenticated shopper token allows the shopper to access all Commerce API features. You can only get an authenticated shopper token when the shopper explicitly allows your application to access their data. Only the shopper can grant this token. To get an authorized token, you must send the shopper to the Digital River platform for authentication. Your application has access to the full API after a shopper enters their credentials and explicitly grants your application permission to access their protected resources.

Option 1

Before a returning shopper signs in, send the POST /oauth20/token?grant_type=password request.

cURL

curl --location --request POST 
'https://api.digitalriver.com/oauth20/token?grant_type=password' \
--header 'authorization: bearer ***\
...

200 OK response

{  
    "access_token": "your_access_token",  
    "token_type": "bearer",  
    "expires_in": "3599",  
    "refresh_token": "your_refresh_token"
}

When the shopper signs in, send the POST /oauth20/token request to create an authenticated shopper token for the shopper session for a Digital River-hosted or client-hosted shopper. When you create an authenticated shopper token for an application using client credentials, include your base64-encoded API key and secret in the request header.

Digital River-hosted shopper example

cURL for a Digital River-hosted shopper

curl --location 'api.digitalriver.com/oauth20/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {{authorization}}' \
--header 'Cookie: {{token}}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

200 OK response

{
    "access_token": "your_access_token",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "your_refresh_token"
}

Client-hosted shopper example

cURL for a client-hosted shopper

curl --location --request POST 'https://api.digitalriver.com/oauth20/token' \--header 'Accept: application/json' \--
header 'Content-Type: application/x-www-form-urlencoded' \--header 'Authorization: Basic {{authorization}}'\--
--header 'Cookie: {{token}}' \
data-urlencode 'grant_type=client_credentials'
data-urlencode 'dr_external_reference_id={{externalID}}' \--
...

200 OK response

{
    "access_token": "your_access_token",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "your_refresh_token"
}

Option 2

Before the returning shopper signs in, use the GET /oauth20/authorize resource to create an authenticated shopper (full access) token. This resource will return a 302 Found response that you can use to direct the user to an IDP-hosted login page. After the shopper logs in successfully, control returns to your application through the redirect URI query parameter, which contains a full access token parameter you can use to make subsequent API calls.

cURL

curl --location --request GET 'https://api.digitalriver.com/oauth20/authorize?client_id={apikey}&response_type=token&dr_limited_token={limited_token}&redirect_uri={redirect_uri}'
...

200 OK response

{  
    "access_token": "your_access_token",  
    "token_type": "bearer",  
    "expires_in": "3599",  
    "refresh_token": "your_refresh_token"
}

The workflow that an application should implement depends on the type of client, which can be Public.

You can include an anonymous shopper (limited access) token as a query parameter to transition the shopper state to an authenticated shopper (full access) token.

This Token API identifies a shopper session and consists of an access_token and a refresh_token. They correspond to the session cookie and the browser cookie. You can save the access_token and refresh_token in the application and use them in subsequent queries. The access_token expires after a specified interval (60 minutes by default in user session site settings in Digital River. The refresh_token expires after one year.

The expires_in property is the time-to-live (TTL) value for the access token. You can refresh the access token at any time.