Release NotesAnnouncementsVideosCommunityBlog
Guides

Authenticate with OAuth—Canada and US

North America—United States and Canada

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

Before you begin

Clover has introduced expiring tokens that are generated using a new v2/OAuth flow for apps in the United States and Canada. In this context, note the following:

  • If you create apps for Europe or Latin America, use the v1/OAuth flow for your apps. See Authenticate with OAuth—Europe and Latin America.
  • If you create apps for North America—the United States and Canada, use the instructions in this topic to create expiring authentication tokens with an access_token and refresh_token pair.

📘

NOTE

To migrate from the legacy v1/OAuth flow to the v2/OAuth flow, see Migrate legacy OAuth API tokens to v2/OAuth expiring tokens.

To learn more about the v2/OAuth flow and expiring tokens, see:

Why use OAuth?

OAuth is the industry-standard protocol for online authorization. Due to the sensitivity of merchant data, Clover has implemented the OAuth 2.0 security framework.

When a merchant selects and installs your app from the Clover App Market, Clover uses OAuth to secure the communication between your app and the merchant and to grant your app the necessary access to merchant data. Your app may need to access data about Clover merchants, such as their order history or current inventory, using the Clover REST API.

For more information, see Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.

Watch video: Clover v2/OAuth expiring tokens

Watch Learn

In this video, learn:

  • What expiring tokens are.
  • How to generate access and refresh tokens.
  • How to migrate an existing app to use expiring tokens.
  • How to start the OAuth flow from the Merchant Dashboard left navigation app link.

View or download: Clover expiring tokens slides

Terminology

The following terms are used in the OAuth flows to generate an OAuth token:

TermDescription
Client ID or App IDApp ID or Client ID that uniquely identifies an app on Clover App Market. This ID is also used to confirm that your app is participating in the OAuth 2.0 flow.
Client Secret or App SecretApp Secret or Client Secret is a secret key that Clover assigns to your app. Do not share the Client Secret key publicly.

Note: Both the App ID and App Secret are automatically assigned when you create an app. You can view the App ID and App Secret on the App name - App Settings page. Both these values are required for you to authenticate your app with the Clover server and make authorized and authenticated requests to Clover merchant data.
Merchant IDMerchant identifier or merchantId that uniquely identifies Clover merchants, including test merchants, on the Clover platform. See Locate the test merchant identifier (merchantId).
MerchantClover merchants can be either unauthorized or authorized to connect to your app.

- 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 using the following URL format:https://sandbox.dev.clover.com/oauth/authorize?client_id={APP_ID}
- An authorized merchant has logged in to their Clover merchant account. The Clover server redirects the merchant to your app with an authorization code using the following URL format:
-- In the legacy v1/OAuth flow: https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE}
-- In the v2/OAuth flow: https://www.example.com/oauth_callback?code={AUTHORIZATION_CODE}&merchant_id={MERCHANT_ID}
Authorization CodeClover redirects an authorized merchant logged into the Merchant Dashboard to your app along with an authorization code. The Clover server provides this temporary auth_code after the merchant is authenticated. This auth_code is exchanged for an access token during the OAuth flow.
Site URLLink or URL for your app that you set on the Edit REST Configuration page for web apps. Your merchant is redirected to this link after they install your app and launch it from the Merchant Dashboard. The Clover server sends authenticated merchants to the Site URL through the/oauth/authorize flow, where they can log in or select their merchant account.
Alternate Launch PathAlternate launch path link or URL for your app that you set on the Edit REST Configuration page for web apps. Your merchant is redirected to this link after they install and launch the app from the Merchant Dashboard. This alternate path URL is required for the oauth/v2/authorize flow, as it:

- Uses the expiring tokens to authenticate with APIs.
- Sends the merchant directly to your app and initiates the OAuth flow.
OAuth or API Token
access_token		Your app uses the Authorization Code, Client ID, and Client Secret to negotiate with the Clover server for an OAuth API token or access_token. With the API token, your app can make REST API calls and access merchant data. See Use Clover REST API.

Access token generated with the oauth/v2/authorize flow expires after some time and is generated in a pair with a refresh token. This v2/OAuth flow-generated access and refresh token pair is known as an expiring token.
Refresh token
refresh_token		One-time-use token that is used to generate another access token when it expires. Refresh tokens are valid for a longer period than the access token but also expire. Clover limits the number of active refresh tokens an app can have for each merchant.
Expiring tokenAn access_token and refresh_token pair is called an expiring token.

Generate a v2/OAuth token

Complete the following steps in the v2/OAuth flow to get an OAuth API token.

Prerequisites

Before you can get an OAuth API token, you need to 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. For more information, see Ecommerce app permissions.

  5. Required for the v2/OAuth flow—Set the Alternate Launch Path to redirect merchants to this link after they install and launch your app from the Merchant Dashboard.

    App Settings on the Developer Dashboard: Edit REST Configuration page

    App Settings on the Developer Dashboard: Edit REST Configuration page

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 URL as a query parameter. From there, your app must call the /oauth/v2/authorize endpoint to initiate the OAuth flow and get an access 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.

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 as a query param to initiate OAuth.

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

    2. For token exchange, your app makes a POST request with—client_id, client_secret, and authorization_code—to /oauth/v2/token. In response, an access and refresh token pair is retrieved.

      Sample: Access and Refresh token pair

      Sample: Access and Refresh token pair

Once the authorization flow is complete, the page for your app displays the access and refresh token pair. Use this API access_token to generate an Ecommerce API key that you need to tokenize a card. See Generate an Ecommerce API key (PAKMS key).

Understand the v2/OAuth flow

If you create apps for North America—the United States and Canada, use the following list of contents to understand the v2/OAuth flow to create expiring authentication tokens:

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.

Request pathSandbox URLProduction URL (North America)
/oauth/v2/authorizesandbox.dev.clover.comwww.clover.com
/oauth/v2/tokenapisandbox.dev.clover.comapi.clover.com
/oauth/v2/refreshapisandbox.dev.clover.comapi.clover.com
/oauth/token/migrate_v2apisandbox.dev.clover.comapi.clover.com

Related topics

Updated about 1 month ago

Related topics