OAuth 2.0

OAuth Overview

The OAuth flow begins when a merchant clicks the icon for your app on their Clover merchant dashboard, and results in the merchant landing on your site URL. Your app will also receive a code for retrieving the secure token used to access that merchant’s data through the REST API.

Confirm Merchant Authorization

If a merchant visits your website and the request does not contain a code, redirect them to https://sandbox.dev.clover.com/oauth/authorize. This will prompt them to log in to their merchant account and/or install the app, if they haven’t done so already. It will then redirect the merchant back to your website.

Your Request’s Query Parameters
  • client_id (required): Your application’s unique ID, which can be found in the application properties on the Developer Dashboard.
  • redirect_uri (optional): If you wish to redirect clients to a URL different from your site URL, you can specify the URL here. The redirect_uri must be a subpath of the site URL you specified in your app’s settings.
  • response_type (optional): By default, Clover will respond to all requests with an authorization code. This is the only secure approach for public-facing web applications. For client-based (JavaScript and mobile) applications not supported by a server and intended to be merchant-facing only, Clover can also respond to the token response type (see Response Type Token Method).
  • state (optional): An opaque value your client uses to maintain state between the request to the Clover authorization server and the callback returning the user to your site. The Clover authorization server includes this value when redirecting the user-agent back to your client. This parameter should be used for preventing cross-site request forgery.
  • client_ids (optional): Specify a comma-separated list of application IDs. If you are deploying your app to multiple markets, you will have a unique application ID for each Clover region you support.
    Example: &client_ids=HENXXTCZ3QP2,ADFZLTQZ3Q9R
  • merchant_id (optional): If your application already knows the merchant_id for the user, you can specify it here. If the user has multiple merchants, this will allow them to skip the “select a merchant” step during the OAuth flow.
Example redirect for an unauthorized user
https://sandbox.dev.clover.com/oauth/authorize?client_id={appId(s)}&redirect_uri={your site's redirect URL}

Request From an Authorized Merchant

When a merchant who’s logged in and subscribed to your app selects your app from the dashboard, they will be taken to the site URL you defined in your app’s settings on the Developer Dashboard. If you specified a redirect_uri while confirming a merchant’s authorization, then the merchant will be taken there instead. A properly authorized merchant will be directed to your site with the following parameters:

Clover’s Request Query Parameters
  • merchant_id: An ID that uniquely identifies the merchant who has authenticated with your app.
  • client_id: The application ID that the user is authenticated to. If your app supports multiple markets (and you specified the client_ids parameter in the request to/oauth/authorize, then use this value to determine which of your apps the user authenticated against.
  • employee_id (optional): The employee ID of the current user. You can use this value to identify whether the current user is the owner of the merchant account, an employee, or someone else. This value is not always present. If a Customer Support agent logs in to your web app, then no employee_id will be provided because the agent is not an employee of the merchant.
  • code: See the Process Authorization Code section below.
Example

This is an example of a Clover-generated request to redirect a logged-in merchant to a developer app.

https://www.example.com/oauth_callback?code=12345678-9abc-d123-4567-516171819201&merchant_id=EHFABCCE7D1SA&employee_id=ZX23RCCE7D1P1&client_id=HENXXTCZ3QP26

Process Authorization Code

Unless you’re using the Response Type Token Method, Clover will direct logged-in merchants to your site with a code in the URL’s query parameters. The code value can be used to obtain an authcode by calling the /oauth/token endpoint with your client_id, client_secret (the app secret listed on your dashboard apps page), and the value of the code query parameter. The response to this request will include a JSON object containing an access_token.

Note

Because the request used to exchange your code for an auth token requires sensitive data (i.e., your app secret), the request does not have CORS support and must be completed server-to-server.

Parameters

Note: The following are the parameters for a GET request. A POST request should contain a JSON object with these attributes.

  • client_id: Your application’s unique ID, which can be found in the application properties on the Developer Dashboard
  • client_secret: Your client secret key, which can also be found in your application properties (and should not be shared publicly)
  • code: The value of the code parameter from the URL the merchant was redirected to after authorization via the Authorization Code Method

Example request to get an access_token

https://sandbox.dev.clover.com/oauth/token?client_id={appId}&client_secret={appSecret}&code={codeUrlParam}
Response

On a successful request, the server responds with a JSON object that contains anaccess_token.

Example
{"access_token": ”[your access token]”}

Response Type Token Method

Important

The Response Type Token Method of authorization makes your secure token publicly accessible to the client. This is unacceptable for public-facing apps. This approach should only be used as necessary for client-based (JavaScript and mobile), merchant-facing applications that aren’t supported by a server.

In order to use the Response Type Token Method, set your app’s Default OAuth Response to Token in your app’s settings page under Web App. When your app completes the “Confirm merchant” authorization step, it should pass the response_type parameter with a value of Token.

When a logged-in user is directed to your site, an access_token will be included as a query parameter after the # character.

Example

http://example.com/javascript_app?&merchant_id={merchantID}&employee_id={employeeID}&client_id={yourAppId}#access_token={yourAccessToken}

If you’re using the Access Token method, you will already have an access_token and will not need to use this endpoint.

Next Steps

Make API calls with your access token.