Search form

Privacy API: Integrate your Bazaarvoice solution into your privacy regulations compliance workflow using a secure HTTP interface.

OAuth2 2-legged Workflow

The Bazaarvoice Privacy API provides a secure HTTP interface for integrating Bazaarvoice into your privacy regulations compliance workflow. To learn more, go to the Privacy API home page.

Contents

(+ show- hide)

This tutorial explains how to use OAuth2 with the Bazaarvoice Privacy API using a two-legged workflow, which authenticates directly between the OAuth2 API and your privacy application. If you want to require that a Bazaarvoice Portal user supply credentials to complete the authentication process, refer to the 3-legged OAuth2 workflow topic.

Introduction

⚠
Privacy requests made with OAuth2 client credentials (2-legged) would not include Curalate client's content.

Bazaarvoice has implemented 2-legged OAuth2, an open standard for access delegation. This style of OAuth is referred to as “2-legged” because it consists of two roles:

  • The Client Application
    This is an application that would like to access data or interact with a Bazaarvoice service.
  • The OAuth2 API
    A Bazaarvoice service that implements the OAuth2 standard and intermediates with the Client Application.

2-legged OAuth2 offers certain advantages including:

  • Authentication is handled server to client and does not require an end user to manually supply credentials.
  • As a well-known open standard, OAuth2 is easier to implement than a custom solution.

Continue reading to learn how to use OAuth2 to access the supported Bazaarvoice APIs.

OAuth2 components

The following table summarizes several components that will be used when implementing OAuth2.

These terms are used throughout the rest of this documentation. Familiarizing yourself with them will make understanding OAuth2 easier.
Component Description

Access Token

A token that, when combined with the Client Secret, allows the Client Application to access data or interact with a Bazaarvoice service. The Access Token is provided by the OAuth2 API and has a lifespan of 60 minutes.

Client Secret

A value used to verify the identity of the Client Application. This value will be provided by Bazaarvoice when the Client Application is registered.

⚠ The value should not be exposed to the public.

Client ID

A value used to identify the Client Application. This value will be provided by Bazaarvoice when the Client Application is registered.

API fundamentals

Security

All requests to the OAuth2 API must use HTTPS.

https://api.bazaarvoice.com/auth/...

Environments

The OAuth2 API supports the following environments:

Staging
Domain stg.api.bazaarvoice.com
Description

Used while developing your application. This environment will not access real end-user information.
Production
Domain api.bazaarvoice.com
Description

Used when your application is complete. This environment will access real end-user information.
⚠
For the remainder of this tutorial, [stg.]api.bazaarvoice.com will be used to indicate that a request can be performed in either environment.

API passkeys

Each request to the OAuth2 API must be accompanied with a staging or production passkey corresponding to the environment used.

Staging https://stg.api.bazaarvoice.com/…/auth?passkey={STAGING_PASSKEY}
Production https://api.bazaarvoice.com/…/auth?passkey={PRODUCTION_PASSKEY}

The OAuth2 API will always be used in a conjunction with the Privacy API, so as a convenience the passkeys for each will be the same. In other words, your Privacy API staging passkey will also work as your OAuth2 API staging passkey and your production Privacy API passkey will also work as your OAuth production API key.

Walkthrough

The following sections describe the recommended method for implementing authentication for your application. The API calls you make to the OAuth2 API count towards your passkey's rate limit and quota, so correct implementation is highly recommended.

The Bazaarvoice OAuth2 integration can be divided into the following action:

  • Token exchange
    • Description: Client Application submits the Client Secret and Client ID to Bazaarvoice. If they are valid, Bazaarvoice will return an Access Token that the Client Application can use when making requests to a Bazaarvoice Service.
    • When to perform: When you don’t have a valid Access Token.

Token exchange

Step 1: Requesting an Access Token with the Client Secret and Client ID

The Client Application requests a token by submitting the application credentials to the OAuth2 API, as depicted below:

⚠
This request should be done on the server and should use HTTPS.

Request

POST https://[stg.]api.bazaarvoice.com/auth/v1/oauth2/token?passkey={API_PASSKEY}
Content-Type: application/x-www-form-urlencoded
…

grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}

Ellipsis (…) in the example above indicate your application may generate other headers.

If successful, the OAuth2 API will respond with the following Access Token data:

Response

{
  "access_token": "{ACCESS_TOKEN}",
  "token_type": "Bearer",
  "expires_at": {TIME_STAMP},
  "scope": "offline_access",
  "refresh_token": "null"
}

The Access Token can now be used to authenticate requests to other Bazaarvoice services.

Step 2: Persist the token data

The Client Application should store the entire token response object. Exactly how this is accomplished is up to the Client Application developer.

⚠
Don't expose the token response object to the public. It should be kept private and secure at all times.

Next

Now the Client Application can use the Access Token to make secure requests to Bazaarvoice. Before each request, verify that the Access Token is still valid and will not expire in the near future. If the Access Token is expired or will expire soon, then repeat the steps in this section to generate a new Access Token.

Resources

Refer to these resources for more information on OAuth2:

  1. OAuth2 2-legged specification
  2. OAuth.net
  3. OAuth Bible on GitHub