High-trust apps securely store and use the Client Secret (app_secret), as shown in the diagram:

Auth code flow for high-trust apps

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.

Generate an access and refresh token pair

Before you begin

See the OAuth terminology section to understand the key terms.

Prerequisites

This section contains steps for the global developer platform. If you are creating apps for merchants in Europe or LATAM—Argentina, complete the steps to create a sandbox developer account.

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. See Set app link (URL) and CORS domain.

Step 1: Request merchant authorization

The merchant needs to log in to the Clover Merchant Dashboard and install the developer's app from the Clover App Market. By installing the app, the merchant authorizes it to access the merchant's information that the app requires.

When an unauthorized merchant installs your app from the Clover App Market, they are redirected to log in to their Clover merchant account and then back to your app.

1. From your app, send a GET request to the /oauth/v2/authorize endpoint.
2. Include the query parameters: client_id and client_redirect_URL.

https://apisandbox.dev.clover.com/oauth/v2/authorize?client_id={APP_ID}&redirect_uri={CLIENT_REDIRECT_URL}

Step 2: Receive an authorization code

Once a merchant is authorized, the Clover server redirects merchants to your app with an authorization code.

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

With the authorization code, the Clover server confirms that the merchant authorizes your request for merchant data. Use this code to further negotiate with the Clover server for an expiring OAuth API token. Every time a merchant is redirected to your app, you can confirm whether the merchant has logged in to their Clover merchant account by checking for an authorization code in the redirect URL.

Step 3: Request and receive an access_token and refresh_token pair

To exchange the authorization code for an expiring OAuth API token:

1. From your app, send a POST request to the /oauth/v2/token endpoint.
2. Include the query parameters: client_id, client_secret, and auth_code.
3. Optional—If you do not need a refresh token, set the query parameter no_refresh_token to true in the request: /oauth/v2/token?no_refresh_token=**true**. See Bypass refresh token creation in the OAuth flow.

When the Clover server responds to the request, retrieve the expiring OAuth API token from your app server. The response body indicates when the access and refresh tokens expire, and the expiration dates are represented as Unix timestamps.

Request and Response example—Expiring OAuth API token

{
  "client_id": "{APP_ID}",
  "client_secret": "{APP_SECRET}",
  "code": "{AUTHORIZATION_CODE}"
}

{
    "access_token": "{ACCESS_TOKEN}",
    "access_token_expiration": 1677875430,
    "refresh_token": "{REFRESH_TOKEN}",
    "refresh_token_expiration": 1709497830
}

Related topics

• Understand the Clover v2/OAuth flow
• Generate OAuth expiring (access and refresh) token
• Use refresh token to generate new expiring token
• Blog: Expiring OAuth Tokens: Securing Clover Merchant Data