Authenticating with OAuth 2.0

Whenever a shared merchant installs your integration (app) for the first time, a standard OAuth 2.0 flow will be initiated, in which:

The merchant installs the integration and grants you access to their Yotpo data.
You create an access token to the App Developer APIs.
You access the relevant API endpoints needed for your app.
The merchant can uninstall the app.

The diagram below illustrates the process for a new shared merchant installing your app.
Underneath the diagram is a detailed breakdown for each step:

Step 1: App Installation

Yotpo's infrastructure allows merchants to start installing 3rd party apps either from their Yotpo merchant account or from your product. Here's how you can support both installation flows:

App Installation from the Yotpo admin

The merchant clicks to install the app from within Yotpo admin.
The merchant is prompted to authorize your app.
They are redirected to your start installation link, provided by you.
The merchant logs into your admin and chooses the specific account to connect to if there is more than one. They are prompted to authorize the Yotpo app.
The merchant is redirected to an installation link in the following format: https://integrations-center.yotpo.com/app/#/install/applications/{{kong_client_id}}?state={{state_param}}

📘
Please note:
Replace {{kong_client_id}} with your unique kong_client ID (aka “Application ID”), which you’ll receive from Yotpo upon the approval and registration of your app. For more information about adding a state param to your call, see this article.

The merchant is redirected back to Yotpo and immediately back to your admin (using the redirect URL you provided as part of the app registration process).
The merchant's Yotpo API Key and Temporary Code are appended to the end of the redirect URL.

👍
Example:
If your redirect URL is https://www.partner.com/yotpo_integration/yotpo_callback,
the following URL will be sent:
https://www.partner.com/yotpo_integration/yotpo_callback?code={{yotpo_temp_code}}&app_key={{yotpo_app_key}}**&state={{state_param}}]**

🚧
Please note:
If you are not able to provide an install URL that will prompt the user to log in and choose the relevant instance to connect to Yotpo, you may provide a simple URL that links to the page within your product where the Yotpo integration can be initiated by the merchant.
This path is not recommended as it creates sub-optimal merchant experience. If you choose to take this option please clearly indicate this to your Yotpo product partner manager.

App Installation from partner’s admin

The merchant clicks to install the app from your admin. They are redirected to an installation link in the following format:

https://integrations-center.yotpo.com/app/#/install/applications/{{kong_client_id}}?state={{state_param}}

📘
Please note:
Replace {{kong_client_id}} with your unique kong_client ID (aka “Application ID”), which you’ll receive from Yotpo upon the approval and registration of your app. For more information about adding a state param to your call, see this article.

The merchant logs into their Yotpo admin. They are prompted to authorize your app.
The merchant clicks Authorize and is redirected to the Yotpo integration section within your admin (using the redirect URL you provided as part of the app registration process).
The merchant's Yotpo API Key and Temporary Code are appended to the end of the redirect URL.

👍
Example:
If your redirect URL is https://www.partner.com/yotpo_integration/yotpo_callback,
the following URL will be sent:
https://www.partner.com/yotpo_integration/yotpo_callback?code={{yotpo_temp_code}}&app_key={{yotpo_app_key}}**&state={{state_param}}]**

Step 2: Generate an access token

Generate an access token using the following information:

The temporary code returned in the redirect URL as ‘code’ (received in step 1)
Your client ID, also known as the kong_client_id, received as part of the application registration
Your client secret, received upon registering your app

The access token is generated once per merchant and does not expire unless the merchant removed the integration in Yotpo or there is a security concern. If you receive 3 repetitive 401 errors after establishing a successful connection, your token probably expired and you should update the status of the integration in your admin to reflect that the merchant needs to re-install the integration.

📘
Please note:
When accessing the different API endpoints, you will also need the yotpo_app_key, which is the specific merchant's public store ID in Yotpo, returned in the redirect URL after the app was authorized by a merchant.

The access token is generated once per merchant and does not expire.

Step 3: Call the API

Use the access token generated in step 2 to access all other API endpoints in the App Market API reference. You can find information specific to your product or use case in the best practice guides below.

📘
Integrating with multiple stores in Yotpo
The access token you receive will only apply to the specific store instance in Yotpo that the merchant picked and authorized the app for. If the merchant has additional stores within their Yotpo account (whether for different languages, testing or multiple brands), they will need to install the same app on each of these stores separately.

Step 4: Allow removal of the app

For privacy and troubleshooting purposes, we require that all apps allow merchants to ‘uninstall the app’ and prevent future access to the API. You will need to support both of the following options for a merchant to uninstall your app:

Uninstall initiated within your product - to uninstall an app, simply add an ‘uninstall’ button on your interface that uses the remove application endpoint. The access token will expire and you will be able to generate a new token if the merchant initiates a new install. The option to re-install the app must appear immediately.
Uninstall initiated within Yotpo - partner-built applications can also be uninstalled by merchants from within the Yotpo admin- once you receive a 401 API response for a merchant, there is a good chance the integration was uninstalled and needs to be re-installed by the merchant within your platform (let the merchant initiate a new install flow, if they would like to).

Once a merchant clicks the “Disconnect” button within Yotpo, an uninstall event will be sent in real-time to you via the uninstall webhook. You will need to register to the webhook as described here as part of your app creation. The access token will be deleted by Yotpo, and the “connect” button on the integration page within Yotpo will re-appear. You should immediately allow the merchant to reinstall the app in your product as well.

📘
How to register for the uninstall webhook?
See all details here.