This topic explains how Clover implements OAuth principles in its application authentication paradigm.

Why use OAuth?

OAuth 2.0 is the industry-standard protocol for online authorization.

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

Considering the sensitivity of merchant data, Clover uses the industry-standard OAuth 2.0 security framework for third-party developers to authenticate their apps with merchant accounts and let them use Clover’s public REST APIs on behalf of the merchant. When a merchant selects and installs your app from the Merchant Dashboard left navigation menu or the Clover App Market (in production environments), the OAuth flow begins.

Prerequisites to get an OAuth token

Before you can obtain an OAuth token, complete the following tasks:

• Create a sandbox developer account.
• Create an app—Note the app ID (client ID) and app secret (client secret) for use later.
• Create your test merchant.

Sandbox and production environment URLs

Clover sandbox and production environments use different URLs. The following table lists which URL to use for OAuth requests in each environment.

📘

NOTE

The Clover v2 OAuth flow, is only available in North America.

Low trust and high trust apps

Clover distinguishes between apps that more securely store and use their client secrets, and apps that do not.

• Low trust apps—Have no secure way to store and use a client secret (app secret)— such as mobile, single-page, and native desktop applications. Previously, low trust apps used the response type token (implicit) auth code flow. Clover now requires that low trust apps use the auth code flow with PKCE. If your Clover app uses the implicit flow and is considered to be a low trust app, migrate your app to use the auth code flow with PKCE.
• High trust apps—Securely store and use a client secret (app secret). High trust apps can use the standard auth code flow to generate auth tokens.
  See Auth code flow for high trust apps for more information.

Watch video: Clover OAuth expiring tokens

OAuth terminology

A few definitions help to understand the OAuth flow:

• Access token (access_token)—Used to access Clover APIs. Access tokens expire after a period of time.

🚧

IMPORTANT

The following values for access and refresh tokens are dynamic and can change:

• Token expiration displays in the response body. Tokens created later can have different durations until they expire.
• Token lengths are not fixed.

Do not hard code access and refresh token expirations or lengths so that you can handle any future updates.

• Alternate Launch Path—Sends the merchant directly to your app at the path specified in the field and initiates the v2 OAuth flow. See Initiate OAuth flow from Merchant Dashboard left nav app link for more information.

• Authorization code (code)—An authorized merchant is redirected to your app along with an authorization code. With this code, the Clover server confirms that your request to access merchant data is authorized by the merchant.

• Client ID (client_id)—Uniquely identifies your app on the Clover App Market. This ID confirms that your app is participating in the OAuth flow. Your client ID is the App ID value in your app's Settings page on the Developer Dashboard.

• Client secret (client_secret)—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.

  🚧

  IMPORTANT

  Do not share the client secret key publicly.

• Merchant ID (merchant_id)—Uniquely identifies a merchant account or business. App users can own multiple merchant accounts and businesses. If an app user has multiple merchant accounts, the user can select the desired merchant account as part of the OAuth flow.
  You can allow the user to skip the account selection step if you set the merchant_id parameter with the merchant ID of that account.

  A merchant who wants access to your app, but has not logged in to their Clover merchant account is an unauthorized merchant. Your app redirects the merchant to log in to their merchant account with the URL https://sandbox.dev.clover.com/oauth/authorize?client_id={APP_ID}.

  When a merchant logs in to their Clover merchant account, they become an authorized merchant. The Clover server redirects this merchant to your app with the URL https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE}.

• Proof key for code exchange (PKCE)—Created to better secure mobile apps, but it is valuable across all OAuth clients. PKCE removes the need to pass the client secret by using the following parameters:

  • Code verifier (code_verifier)—Unique random string that the application creates for every authorization request.
  • Code challenge (code_challenge)—Application hashes the code verifier resulting in the code challenge. Clover currently supports SHA256 (secure hash algorithm 256 bit) to one-way hash the code verifier. Other algorithms may be added in the future.

• Redirect URI (redirect_uri)—After the merchant has logged in to their account, you can redirect them to a custom URL with the redirect_uri parameter. 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.

• Refresh token (refresh_token)—A token that is used to generate more access tokens. It is a one-time-use token used to generate another access token when it expires. Refresh tokens expire, but they are valid for a longer period of time than the access token.
  Refresh tokens tend to accumulate in the database and can cause performance issues or other technical maintenance issues. Clover sets a limit on the number of refresh tokens a single application can have active for each merchant.

🚧

IMPORTANT

The following values for access and refresh tokens are dynamic and can change:

• Token expiration displays in the response body. Tokens created later can have different durations until they expire.
• Token lengths are not fixed.

Do not hard code access and refresh token expirations or lengths so that you can handle any future updates.

• State (state)—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.
  Suppose the Clover server response also includes the same state parameter value. In that case, this ensures that your app makes a legitimate request and the Clover server has redirected the merchant to your app in response to the legitimate request.

📘

NOTE

To learn more about auth tokens, see our blog post Expiring OAuth Tokens: Securing Clover Merchant Data.

Auth code flows

Clover apps use the following auth token acquisition flows:

• Implicit flow—Also called response type token, this is the least secure auth flow. Implicit flow is a simplified auth flow that can not securely store a client secret. The access token is returned immediately without an extra authorization code exchange step. Implicit flow was previously recommended for native and JavaScript apps that can not securely store a client secret.

  🚧

  IMPORTANT

  Clover plans to deprecate the response type token (implicit) flow. If your app uses response type tokens, migrate your app to use the auth code flow with PKCE. See Legacy token migration flow for more information.

• Authorization code flow—Used by high trust clients to exchange an authorization code for an access token. After the redirect URL returns the merchant to the application, the app receives the authorization code from the URL and uses it to request an access token.

• Authorization code flow with proof key for code exchange (PKCE)—Required for all applications that can not securely store a client secret, but especially for standalone mobile, desktop, and single-page applications.

Compare: Legacy response type token (implicit) flow with PKCE flow

Comparing the implicit flow and auth code flow with PKCE illustrates the added security steps in the auth code flow with PKCE.

Additional References

To learn more about the OAuth protocol, visit OAuth.net.

To learn more about Clover auth tokens, see our blog post Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys