Overview

In the v2/OAuth flow, an expiring token consists of an access_token and refresh_token pair. The access token is short-lived, while the refresh token lasts longer but also expires eventually. To maintain authorization, your app must generate a new token pair before the current one expires. To do so, send a POST request to the /oauth/v2/refresh endpoint with the existing refresh_token to generate a new access_token and refresh_token pair. Your app needs to handle the refreshing of access tokens to allow merchants continuous access to the app.

Key features of expiring tokens

Key features of access and refresh tokens are:

• Limitations on the number of refresh tokens—Clover limits the number of active refresh tokens an app can have for each merchant. If an app exceeds the limit, prior tokens become invalid.
• Limitations on refresh token usage—Refresh token is for single use and becomes invalid immediately after a new access_token and refresh_token pair is generated using the /oauth/v2/refresh endpoint.
• Dynamic expiration dates and length—You should not hard code access and refresh token expirations or lengths but handle them dynamically in your app:
  • Token expiration date is based on the time the token is generated; hence, tokens created over a period of time have different expiration dates. The format of the expiration dates is Unix timestamp.
  • Token length is not fixed.

Before you begin

Review the following information:

• Authenticate with OAuth—Canada and US for OAuth terminology.
• Understand the Clover v2/OAuth flow for information on high-trust and low-trust app authentication flow.

Generate new access and refresh tokens

1. Generate OAuth expiring (access and refresh) token.
2. Send a POST request to the /oauth/v2/refresh endpoint.
3. Include the client_ID and refresh_token from the response body in step 1.

Request and Response example—Generate new access and refresh tokens

{
    "client_id": "{APP_ID}",
    "refresh_token": "{REFRESH_TOKEN}"
}

{
    "access_token": "{NEW_ACCESS_TOKEN}",
    "access_token_expiration": 1709498373,
    "refresh_token": "{NEW_REFRESH_TOKEN}",
    "refresh_token_expiration": 1741034373
}

The response body displays the new access and refresh token, along with their expiration date, in Unix timestamp format.

Bypass refresh token creation in the OAuth flow

Clover limits the number of active refresh tokens that an app can have for each merchant. In some scenarios, a refresh token is not needed, for example, in:

• Frontend apps that use OAuth to authenticate users to their own apps often don’t need a refresh token.
• Apps that only need the access token to verify that the user successfully authenticated with Clover and then use that token to get details from the API.

In such cases, generating a refresh token may cause the app to reach the limit unnecessarily. Use the no_refresh_token setting on the OAuth Authorize endpoint to bypass the refresh token creation.

To bypass generating a refresh token for your app:

1. Install the app and receive authorization information from the /oauth/v2/authorize endpoint.
2. Send a POST request to the /oauth/v2/token endpoint with the following parameters: client_id, client_secret, and authorization_code.
3. Set the no_refresh_token parameter to true.

Request and Response example—No refresh token

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

{
    "access_token": "{ACCESS_TOKEN}",
    "access_token_expiration": 1709498373,
}

The response returns only an access token, along with the expiration date, in Unix timestamp format.

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.