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.

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.

Install the app and receive authorization information from the /oauth/v2/authorize endpoint.
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

Send a POST request to the /oauth/v2/refresh endpoint.
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

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/v2/refresh' \
--header 'content-type: application/json' \
--data '{
    "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:

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

Request and Response example—No refresh token

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/v2/token' \
--header 'content-type: application/json' \
--data '{
    "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.

Use refresh token to generate new expiring token