OAuth 2.0

OAuth Overview

The OAuth flow begins when a merchant clicks your app’s icon on their Clover merchant dashboard, and results in the merchant landing on your site URL along with a code that your app can use to retrieve 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 have not already done so. It will then redirect the merchant back to your website.

Your Request’s Query Parameters
  • client_id: 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 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 used by your client 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. The 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 that you support. Example: &client_ids=HENXXTCZ3QP2,ADFZLTQZ3Q9R
  • merchant_id (optional): If your application already knows the merchant ID for the user then you can specify it here. If the user has multiple merchants this will allow them to skip the “select a merchant” step during OAuth.
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 is logged in, and subscribed to your app selects your app from the dashboard they will be sent 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 sent 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. See the FAQ for details about the merchant_id.
  • 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 Process Authorization code below.
Example

This is an example of a Request generated by Clover, 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 are using the Response Type Token Method, Clover will direct logged-in merchants to your site with a code in the url query parameters. The code value can be used to obtain an authcode by calling the /oauth/token endpoint with your client_id (the ID of your app), 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), there is no CORS support for this request and it must be completed server to server.

Parameters

Note: for a GET requests these should be query parameters. For a POST request the payload should be 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 publicly shared.
  • code: The value of the code parameter from the URL that 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 an access_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) applications not supported by a server, and intended to be merchant facing only.

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 param after the # character.

Example 

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

If you are using the Access Token method, you do not need to use this endpoint since you already have an access_token.

Next Steps

Make API calls with your access token.