Overview

In the v2/OAuth flow, an expiring authentication token is generated. It 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 and client_id 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.

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.

Prerequisite

You need an access_token and refresh_token pair along with the client_id for which you initiated the OAuth flow. For information, see Generate OAuth expiring (access and refresh) token.

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.

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

Generate new access and refresh token pair

1. Send a POST request to the /oauth/v2/refresh endpoint.
2. Include the client_ID and refresh_token from your app's initial token request to the /oauth/v2/token endpoint to generate an expiring token. See Prerequisite.

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.

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