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:

1. The merchant grants you access to their data
2. You authenticate and access the relevant App Developer API endpoints

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: Request authorization

1. 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.

2. The merchant logs into their Yotpo admin. They are prompted to authorize your app.

3. 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 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: Allow removal of the app

For privacy and troubleshooting purposes, all apps must include an ‘uninstall app’ option on the partner’s side. To uninstall an app, simply add an ‘uninstall’ button on your interface that uses the remove application endpoint.

Partner-built applications can also be uninstalled/removed by merchants from within the Yotpo admin. If 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).

Step 4: 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 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.