TABLE OF CONTENTS

• Introduction
• Creating an App Key
• Using an App Key

Introduction

Feefo APIs use the OAuth 2.0 protocol for authentication and authorisation. This page gives an overview of the OAuth 2.0 authorisation scenarios that Feefo supports.

Creating an App Key

To get started using an OAuth 2.0 Token, you must first create an App Key. An App Key can be created in the Feefo Hub, and allows you to control which resources a service can access. An App Key grants access to data for the currently selected merchant and all of its sub-merchants. To create an App Key, navigate to Settings then, under Connectivity, select App Keys, then click “Create App Key”.

You are then taken to the creation page, where you can name your App Key. How you choose to name your App Key is entirely your decision, although we’d recommend ensuring that the name conveys the key’s intent so that it’s easy to identify in future.

You can then select the associated services. This specifies which Feefo services your App Key can be used to access. We recommend limiting the access of your App Key as much as possible to protect your data. For example, if you intend use the key to allow a third-party application access to your Reviews API data, we suggest granting the key access to the Reviews API service only. You can always change this later if you need to.

By default, an App Key will grant access to all of the data for the current account and its sub-accounts. However, in some cases this may not be appropriate. For example, a multiregional organisation may wish to grant access to an application to access data only in a specific region, or a franchisor access to the data from specific franchisees. This behaviour can be achieved through tag restrictions.

If the currently selected merchant does not have any sub-merchants, tag restrictions can be applied that restrict the data accessible through the selected services. Selecting a tag of “region” with the value “North West” would mean that only sales containing a sale tag with the key “region” and the value “North West” would be accessible. You can learn more about sales tags here.

If you select multiple tags, the following rules will be applied: 

If you select multiple values for the same tag key, the sale must contain at least one of the provided tag values. 

If you select values for different tag keys, the sale must contain all of the provided tag keys.

Consider the following example: 

Only sales matching either of the following sales tags combinations will be returned: 

region = “North West” AND category = “Musical Instruments” 

region = “West Midlands” AND category = “Musical Instruments” 

Once you’ve selected the appropriate tags (if required), create the key by pressing “Create App Key” button. 

Using an App Key

The OAuth 2.0 flow is an industry-standard mechanism for granting access to a resource. Feefo's implementation of the client OAuth flow is shown below. You first need to use your App Key credentials to create an access token. The access token can then be used on subsequent requests to access Feefo API resources. 

Once you’ve created an App Key, you’ll be able to see it on the App Keys list page (available at Settings → App Keys). To use the App Key, click the “Details” button. This will take you to a page where you can edit your App Key, and retrieve the credentials. To work with our OAuth 2.0 Auth framework, you’ll need to use the Client ID and Secret shown on this page.

To create an access token, you’ll need to send a POST request, specifying these credentials. Details of this request are outlined below using the Content-Type application/json or Content-Type application/x-www-form-urlencoded.

Request type: POST 
Request URL:
https://api.feefo.com/api/oauth/v2/token
Content-Type: application/json 
Body:


{
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"grant_type": "client_credentials"
}

OR

Content-Type: application/x-www-form-urlencoded 

Body:
 
client_id=your-client-id&client_secret=your-client-secret&grant_type=client_credentials
If your credentials are correct, you will receive a response in the following format: 

{
"access_token": "your-access-token",
"expires_in": 3600,
"token_type": "bearer"
 }

The access_token field contains the access token that you can use to access Feefo's APIs. The expires_in field denotes the number of seconds that the token is valid for. When your token expires, you will need to repeat the token creation request to generate a new token.

With your access token to hand, you can now use it to access Feefo's API services. Once you’ve got a request ready for the service you’re accessing, you can use the access token by adding an Authorization header. The value of the header should be your access token, prefixed by “Bearer" (notice the space after “Bearer”). Specifically: 

Key: Authorization 
Value: Bearer your-access-token