All REST API endpoints require an OAuth-generated access_token with specific permissions. The v2/OAuth flow is used for apps created for Clover merchants in North America—the United States and Canada. This flow generates expiring tokens, which include an access_token and refresh_token pair.

Before you begin

Review the following information:

• Authenticate with OAuth—Canada and US for OAuth information, get started video, and terminology.
• Understand the Clover v2/OAuth flow for information on high trust and low trust apps authentication flow.

Prerequisites

To generate an expiring OAuth API token, complete the following:

1. Create a global developer account.

2. Manage test merchant accounts and information.

3. Create your app in the sandbox environment.

4. Configure settings and permissions that your app requires to access Clover merchant data.

5. Required for the v2/OAuth flow—Set the Alternate Launch Path to redirect merchants to install and launch your app from the Clover App Market.

   

Steps

The Clover v2/OAuth flow starts when the merchant selects your app directly from the Clover App Market or on the Merchant Dashboard > More Tools > Clover App Market page. Clover redirects the merchant to your app with the merchantId included in the Redirect URI as a query parameter. From there, your app must call the /oauth/v2/authorize endpoint to initiate the v2/OAuth flow and get an access_token and refresh_token pair.

If a merchant accesses the app from your website instead of installing and connecting with it from the Clover App Market, your app needs to redirect the merchant to the Clover App Market page to install the app from there. The Alternate Launch Path is used in this case.

To generate an expiring access and refresh token pair:

1. Log in to the Global Developer Dashboard.

2. Navigate to the Merchant Dashboard for your test merchant.

3. From the left navigation menu, click More Tools, and then select your app on the Clover App Market page.

4. Click Connect to install your app for the test merchant.

   From here:

   1. For merchant authorization, Clover redirects the merchant to the location specified in the Alternate Launch Path field, and the app calls /oauth/v2/authorize with the authorization code auth_code as a query param to initiate OAuth.

      OAuth callback format

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

   2. For token exchange, your app makes a POST request with theclient_id, client_secret, and authorization_code to /oauth/v2/token. The response provides an access_token and refresh_token pair that displays on the OAuth Process Results page of your app.

      

---

Request and Response information

For detailed request and response information, see:

• Generate access and refresh tokens for high-trust apps
• Generate access and refresh token pair using PKCE for low-trust apps

---

Generate new OAuth refresh token

The expiring token generated in the v2/OAuth flow is a pair of access_token and refresh_token. The access token is short-lived and expires after some time. When it expires, a refresh token is used to generate another access token. Refresh tokens are valid for a longer period than the access token but also expire.

To prevent your app from becoming unauthorized, you need to generate and use a refresh token before the current access_token and refresh_token pair expire. The /oauth/v2/refresh endpoint is used to exchange the refresh token for a new access_token and refresh_token pair. Your app needs to handle the refreshing of access tokens to maintain continuous access to the app.

For information, see Generate new OAuth refresh token.

---

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.

---

Related topics

• Authenticate with OAuth—Canada and US
• Blog: Expiring OAuth Tokens: Securing Clover Merchant Data
• Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys