Before you begin

Clover has introduced expiring tokens that are generated using a new v2/OAuth flow for apps in the United States and Canada. In this context, note the following:

• If you create apps for Europe or Latin America, you will continue to use the v1/OAuth flow for your apps and use the instructions in this topic to generate OAuth API tokens.
• If you create apps for North America—the United States and Canada, see Authenticate with OAuth—Canada and US to create or migrate to expiring authentication tokens with access_token and refresh_token pair.

Why use OAuth?

OAuth is the industry-standard protocol for online authorization. Due to the sensitivity of merchant data, Clover has implemented the OAuth 2.0 security framework.

When a merchant selects and installs your app from the Clover App Market, Clover uses OAuth to secure the communication between your app and the merchant and to grant your app the necessary access to merchant data. Your app may need to access data about Clover merchants, such as their order history or current inventory, using the Clover REST API.

For more information, see Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.

Watch the tutorial

OAuth in sandbox versus production environment

Our OAuth documentation is created for use with the sandbox environment. To create the OAuth flow for apps on the Clover App Market (in production environments), replacehttps://sandbox.dev.clover.com/ with the correct regional base URL in your requests:

• Europe: https://eu.clover.com/
• Latin America: https://la.clover.com/

Steps in the Clover OAuth flow

There are four key steps in the Clover OAuth flow:

Terminology

To start, let us define a few concepts used in the OAuth flow:

Generate an OAuth token

Complete the following steps in the v1/OAuth flow to get an OAuth API token.

Prerequisites

Before you can generate an OAuth token, complete the following:

1. Set up a sandbox developer account.
2. Create an app in the sandbox environment.
3. Install your app to your test merchant.

Step 1: Request merchant authorization

The merchant needs to log in to the Clover Merchant Dashboard and install the developer's app from the Clover App Market. By installing the app, the merchant authorizes it to access the merchant's information that the app requires.

If an unauthorized merchant installs your app from the Clover App Market, redirect them to log in to their Clover merchant account and then back to your app, using the following format:

https://apisandbox.dev.clover.com/oauth/authorize?client_id={APP_ID}&redirect_uri={CLIENT_REDIRECT_URL}

If an unauthorized merchant navigates directly to your app URL without installing the app from the Clover App Market:

• Redirect the merchant to log in to their Clover merchant account, and then
• Inform the merchant to install your app from the Clover App Market.

Clover provides several parameters to customize the merchant authorization redirect URL. These include: client_id , merchant_id, redirect_uri, response_type, and state.

Step 2: Receive an authorization code

Once a merchant is authorized, the Clover server redirects merchants to your app using the Site URL value (under App Settings > REST Configuration) specified in the test Merchant Dashboard.

📘

NOTE

If you have set the redirect_uri parameter to a custom location as part of the merchant authorization redirect URL, the server then redirects the merchant to the specified location.

The Clover server redirects the merchant to your app along with the parameters: merchant_id, client_id (app_id), employee_id, and authorization_code in the following URL format:

https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&employee_id={EMPLOYEE_ID}&code={AUTHORIZATION_CODE}

With the authorization code, the Clover server confirms that your request for merchant data has been authorized by the merchant. You can use this code to further negotiate with the Clover server for an API token. Every time a merchant is redirected to your app, you can confirm whether the merchant has logged in to their Clover merchant account by checking for an authorization code in the redirect URL.

Step 3: Request and receive an API token

At this stage of the OAuth flow, you exchange your authorization code for an API token. Send an API token request to the Clover server with the parameters: client_id, client_secret, and authorization_code in the following URL format:

https://apisandbox.dev.clover.com/oauth/token?client_id={APP_ID}&client_secret={APP_SECRET}&code={AUTHORIZATION_CODE}

📘

NOTE

Since the API token request consists of sensitive information about your app, this request does not have CORS support. To successfully request an API token, send this request from your app server to the Clover server. When the Clover server responds to the request, retrieve the API token from your app server.

Step 4: Receive an API token

The Clover server responds to your API token request with a JSON object in the following format:

{
  "client_id": "{APP_ID}",
  "client_secret": "{APP_SECRET}",
  "code": "{AUTHORIZATION_CODE}"
}

{
   "access_token":"{API_TOKEN}"
}

The API token has a lifespan of one year.

Use the response_type token method

🚧

WARNING

When you use the response_type token method, the API token from the Clover server is publicly accessible. We highly recommend that you use this method only for merchant-facing apps.

All your apps on the Clover App Market follow the OAuth flow to retrieve an API token from the Clover server. You can also build and publish client-based JavaScript and mobile apps on the Clover App Market. For these client-based apps, Clover provides you with the response_type token method to retrieve an API token as soon as the merchant is authorized.

To use the response_type token method:

1. Log in to your Developer Dashboard.
2. From the left navigation menu, click Your Apps > App name > App Settings. The App name - App Settings page lets you view and configure settings and permissions that your app requires to access Clover merchant data.
3. Select Web app on the App Type page. See Select App Type.
   The REST Configuration displays on the App Settings page.
4. Click REST Configuration. The Edit REST Configuration page appears.
5. In the Default OAuth Response field, select Token (Testing Only).
6. In the merchant authorization redirect URL (step 1 of the OAuth flow), set the value of the response_type parameter as token.

The Clover server directly sends you an API token and redirects the authorized merchant to your app using the following URL format:

https://example.com/javascript_app?&merchant_id={MERCHANT_ID}&client_id={APP_ID}&employee_id={EMPLOYEE_ID}#access_token={API_TOKEN}