OAuth 2.0

While building your Clover app, you may want to access data about Clover merchants, such as their order history or current inventory. With Clover’s powerful REST APIs, your app can easily access data about merchants and their businesses.

Considering the sensitivity of merchant data, we at Clover have implemented the OAuth 2.0 security framework. When a merchant selects and installs your app from the Clover App Market, we use OAuth 2.0 to first secure the communication between your app and the merchant, and then give your app the desired access to merchant data.

In this article, we discuss:

The Clover OAuth 2.0 Flow

As shown in the figure below, there are 4 keys steps involved in the Clover OAuth 2.0 flow.

OAuth 2.0

To begin with, let’s define a few terms that can help us in discussing the OAuth 2.0 flow:

  • CLIENT ID

    This ID uniquely identifies your app on the Clover App Market. This ID confirms that your app is participating in the OAuth 2.0 flow.

    Your client ID is the App ID value in your app’s Settings page on the Developer Dashboard.

  • CLIENT SECRET

    This ID is a secret key that is assigned to your app by Clover. The client ID and client secret together authenticate the identity of your app with the Clover Server.

    Your client secret is the App Secret value on your app’s Settings page. Do not share this key publicly.

  • MERCHANT

    Clover merchants can be either one of two states:

    • An unauthorized Merchant wants access to your app, but has not logged in to their Clover merchant account. Your app redirects this merchant to log in to their merchant account.

      https://sandbox.dev.clover.com/oauth/authorize?client_id={APP_ID}

    • An authorized Merchant has logged in to their Clover merchant account. The Clover Server redirects this merchant to your app.

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

  • AUTHORIZATION CODE

    An authorized merchant is redirected to your app along with an authorization code. With this code, the Clover Server confirms that your request for merchant data has been authorized by the merchant.

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

  • API TOKEN

    Your app uses the authorization code, client ID, and client secret to negotiate with the Clover Server for an API token. With the API token, your app can make REST API calls and access merchant data.

    {
       "access_token":"{API_TOKEN}"
    }
    

Note

Our OAuth 2.0 documentation is written for the sandbox environment. To create your OAuth flow in production environments, simply replace https://sandbox.dev.clover.com/ with our REST API in your requests:

  • United States: https://www.clover.com/
  • Europe: https://eu.clover.com/

Step 1: Request Merchant Authorization

When an unauthorized merchant selects and installs your app from the Clover App Market, redirect this merchant using the following URL format to log in to their Clover merchant account:

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

Tip

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

  1. Redirect this merchant to first log in to their Clover merchant account, and then
  2. Request the merchant to install your app from the Clover App Market

Clover provides a wide range of parameters that you can use to customize the merchant authorization redirect URL as listed in the following table.

Table 1: Parameters in the merchant authorization redirect URL

Parameter Description

client_id

This ID uniquely identifies your app on the Clover App Market.

Note

The client_id parameter value is the App ID value in your app’s Settings page on the Developer Dashboard.

client_ids(Optional)

If you are building an app for multiple Clover markets, your app receives a unique app ID for each Clover market. For such apps, set the client_ids parameter with a comma separated list of app IDs.

merchant_id(Optional)

This ID is assigned by Clover to uniquely identify a merchant account or business. App users can own multiple businesses and merchant accounts. If an app user has multiple merchant accounts, the user is requested to select the desired merchant account as part of the OAuth 2.0 flow.

If you know the merchant account that the user will select, you can simply set the merchant_id parameter with the merchant ID of that account. This enables the user to skip the account selection step.

redirect_uri(Optional)

Once the merchant has logged in to their account, you can redirect them to a custom URL with the redirect_uri parameter.

Note

The value of the redirect_uri parameter must be a subpath of the Site URL value on your app’s Settings > Web Configuration page.

response_type(Optional)

By default, the Clover Server responds to merchant authorization requests by redirecting the merchant to your app along with an authorization code. For your app on the Clover App Market, receiving the authorization code is an important step in the OAuth 2.0 flow.

You can also build and publish client-based JavaScript and mobile apps on the Clover App Market. For such apps, if you set the value of the response_type parameter as token in the redirect URL, the Clover Server follows the Response Type Token method and directly sends you an API token along with redirecting the merchant to your app.

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.

state(Optional)

To ensure that merchants are logging in to a legitimate redirect URL from your app, you can set the state parameter with any string value. In this case, if the Clover Server response also includes the same state parameter value, this ensures that:

  1. An legitimate request has been made by your app, and then
  2. The Clover Server has redirected the merchant to your app in response to the legitimate request

Step 2: Receive an Authorization Code

Once a merchant is authorized, the Clover Server redirects this merchant to your app using the Site URL value on your app’s Settings > Web Configuration page.

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 a set of parameters in the following URL format, which includes an authorization code:

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.

Tip

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.

The following table lists the parameters in the merchant redirect URL from the Clover Server to your app.

Table 2: TParameters in the merchant redirect URL from the Clover Server

Parameter Description

merchant_id

This ID uniquely identifies the Clover merchant account that has been authorized to use your app.

client_id

This ID uniquely identifies your app on the Clover App Market. This parameter confirms that your app is participating in the OAuth 2.0 flow and that the code parameter value is for the specified client_id parameter value.

code

With this 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.

employee_id(Optional)

This ID uniquely identifies the employee from the merchant roster that has logged in to their account. You can create custom rules in your app based on the employee.

Note

If a Clover customer support agent accesses your app on behalf of the merchant, the employee_id parameter is not part of the redirect URL.

Step 3: Request an API Token

At this stage of the OAuth 2.0 flow, you exchange your authorization code for an API token from the Clover Server. Send an API token request to the Clover Server in the following URL format:

https://sandbox.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.

You must set all the parameters as listed in the following table.

Table 3: Parameters in the API token request URL

Parameter Description

client_id

This ID uniquely identifies your app on the Clover App Market.

client_secret

This ID is a secret key that is assigned to your app by Clover. The client ID and client secret together authenticate the identity of your app with the Clover Server when you are requesting for an API token.

Note

The client_secret parameter value is the same as the App Secret value on your app’s Settings page. Do not share this key publicly.

code

With this 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.

Step 4: Receive an API Token

In the final step, the Clover Server responds your API token request with a JSON object in the following format:

{
   "access_token":"{API_TOKEN}"
}

Note

The API token has a life span of 1 year.

Using the Response Type Token Method

All your apps on the Clover App Market undergo the 4-step OAuth 2.0 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. On your app’s Settings > Web Configuration page, set the Default OAuth Response value to Token.
  2. In the merchant authorization redirect URL (Step 1 of the OAuth 2.0 flow), set the value of the response_type parameter as token.

The Clover Server directly sends you an API token along with redirecting the authorized merchant to your app using the following URL format:

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

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.