With Clover REST API, your app has access to data about merchants and their businesses.
Considering the sensitivity of merchant data, Clover has implemented the OAuth 2.0 security framework for generating secure API tokens.
When a merchant installs your app from the Clover App Market (in production environments), we use an OAuth-generated API token to first secure the communication between your app and the merchant, and then to give your app the desired permissions to access merchant data.
OAuth in sandbox vs production
Our OAuth 2.0 documentation is created for use with the sandbox environment. To build the OAuth flow for apps on the Clover App Market (in production environments), simply replace https://sandbox.dev.clover.com/
with the correct regional base URL in your requests:
- US & Canada:
https://www.clover.com/
- EU:
https://eu.clover.com/
OAuth configuration on the Developer Dashboard
While testing the OAuth flow in sandbox, you can retrieve a sample access_token
by completing the following steps.
Set the following configuration on the Developer Dashboard:
- On the sandbox Developer Dashboard, select your app from the side-nav.
- On the App Settings page, click REST Configuration. This setting appears when you set App Type to Web (REST clients).
- On the Edit REST Configuration modal that appears, set Site URL as the landing page of your web app. See Setting app URL & CORS for more information.
- Set Default OAuth Response as Token (Testing Only).
- Click Save.
- On the App Settings page, click REST Configuration.
- Click Example OAuth Request.
- If you have multiple test merchant accounts, click a test merchant's name to select it.
- If you have not already installed the app to your test merchant, the market listing page for your app appears. Click Connect and then, on the install modal, click Accept.
- After the browser redirects to your site, copy the
access_token
value from the address bar.
NOTE
For your app to work in production, you must select Code as the Default OAuth Response.
The Clover OAuth 2.0 flow
As shown in the figure below, there are four key steps involved in the Clover OAuth 2.0 flow.


To start, let's define a few concepts used in 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. Together, the client ID and client secret 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: unauthorized or authorized
Merchant | URL |
---|---|
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. |
|
An authorized merchant has logged in to their Clover merchant account. The Clover server redirects this merchant to your app. |
|
- 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={appId}&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}"
}
Step 1: Request merchant authorization
When an unauthorized merchant selects and installs your app from the Clover App Market, redirect the merchant to log in to their Clover merchant account using the following URL format:
https://sandbox.dev.clover.com/oauth/authorize?client_id={appId}&redirect_uri={CLIENT_REDIRECT_URL}
NOTE
A
redirect_uri
passed to/oauth/authorize
must be a subpath of the set Site URL.For example, if you specify the site URL https://www.example.com/myapp`, the
redirect_uri
ofhttps://www.example.com/myapp/setup
in your OAuth request is valid, buthttps://example.com/setup
is invalid.
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
- Ask the merchant to install your app from the Clover App Market
Clover provides several parameters to customize the merchant authorization redirect URL.
Parameter | Description |
---|---|
| This ID uniquely identifies your app on the Clover App Market. The |
| If you are building an app for multiple Clover App Markets, your app receives a unique app ID for each App Market. For such apps, set the |
| This ID uniquely identifies a merchant business. Merchants can own multiple businesses, locations, and UUIDs. In this case, the merchant is asked to select the name they want to use for authorization and installation. If you know the name that the merchant will select, you can simply set the Send a |
| Once the merchant has logged in to their account, you can redirect them to a custom URL with the If you know the merchant account that the user will select, you can simply set the |
| 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 With this method, the API token from the Clover server is publicly accessible. We highly recommend that you use this method only for merchant-facing apps. |
| 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) a legitimate request has been made by your app, and (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 merchants to your app using the Site URL value (under App Settings > REST Configuration) specified in the sandbox Merchant Dashboard.
NOTE
If you set the
redirect_uri
value 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={mId}&employee_id={employeeId}&client_id={appId}&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.
NOTE
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.
Parameter | Description |
---|---|
| This ID uniquely identifies the Clover merchant business authorized to use your app. |
| 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 |
| 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. |
| This ID uniquely identifies the owner account associated with the merchant business. Send a |
Step 3: Request an API token
At this stage of the OAuth 2.0 flow, you exchange your authorization code for an API token. Send an API token request to the Clover server in the following URL format:
https://sandbox.dev.clover.com/oauth/token?client_id={appId}&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.
Parameter | Description |
---|---|
| This ID uniquely identifies your app on Clover App Market. |
| 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. The |
| 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 to your API token request with a JSON object in the following format:
{
"access_token":"{API_TOKEN}"
}
NOTE
The API token has a lifespan of one year.
Using the Response Type Token method
All your apps on the Clover App Market undergo the 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:
- On the sandbox Developer Dashboard, click App Settings on the side-nav for your app.
- On the App Settings page, click REST Configuration.
- On the Edit REST Configuration modal that appears, set the DEFAULT OAUTH RESPONSE value to Token (Testing Only).
- In the merchant authorization redirect URL (step 1 of the OAuth 2.0 flow), set the value of the
response_type
parameter astoken
.
The Clover server directly sends you an API token and redirects the authorized merchant to your app using the following URL format:
http://example.com/javascript_app?&merchant_id={mId}&client_id={appId}&employee_id={employeeId}#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.
OAuth checklist when moving to production
When you are ready to move your apps from sandbox to production, complete the following OAuth checklist:
Base URL
Update the OAuth base URL. To request merchant authorization, use the following URL:
- US & Canada:
https://www.clover.com/oauth/authorize?client_id={appId}
- EU:
https://eu.clover.com/oauth/authorize?client_id={appId}
NOTE
Do not omit the
www
in the OAuth base URL for US or Canada. Making requests withhttps://clover.com/
will return aNo JSON object could be decoded
response.
App configuration
Your app settings in the sandbox Developer Dashboard must be configured in the production Dashboard. In this process, a new Client ID (App ID) and Client Secret (App Secret) is generated.
NOTE
Every app permission that you have set in the sandbox Developer Dashboard must be set in the production Dashboard as well.
Client ID
Use the new client ID of your app from the production Developer Dashboard in the OAuth flow.
If the client ID is incorrect, you can use your browser's developer tools to identify whether the client_id
value is not recognized. On the Network tab, you can see the 404
status response. Clicking the request shows the following response on the Response tab:
{"details":"No App with ID {appId} found.","message":"Not Found"}
Updated a day ago