If your app uses a non-expiring auth token generated using the legacy OAuth flow, you need to migrate to using an expiring authentication (OAuth) token, which includes anaccess_token and refresh_token pair. The token migration flow includes the option to use Proof key for code exchange (PKCE) for low-trust apps.

Token migration flow with PKCE option

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.

Migrate legacy tokens

To exchange a legacy OAuth token for a new expiring authentication (OAuth) token, which includes a pair of access_token and refresh_token:

Step 1: Generate code_verifier and code_challenge for a low-trust app

If using PKCE in your app:

1. Generate a code verifier—Create a random string between 43 and 128 characters that is stored as part of the OAuth session.
2. Generate a code challenge—Use the code_verifier to generate the code_challenge. For example, with the SHA-256 encryption, the code_challenge = SHA256(code_verifier).

Step 2: Request and receive an authorization code

1. Send a POST request to the/oauth/token/migrate_v2 endpoint.
2. Do one of the following:
   1. For a high-trust app, include the parameters: auth_token, merchant_uuid, app_id.
   2. For a low-trust app, if using PKCE, include the parameters: auth_token, merchant_uuid, app_uuid, and code_challenge.

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

Request and Response example

Expiring OAuth token for high-trust app

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/token/migrate_v2' \
--header 'content-type: application/json' \
--data '{
    "auth_token": "{LEGACY_API_TOKEN}",
    "merchant_uuid": "{MERCHANT_ID}",
    "app_uuid": "{APP_ID}"
}'

{
    "authorization_code": "{AUTHORIZATION_CODE}",
    "expiration": 1678489882
}

Expiring OAuth token for low-trust app

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/token/migrate_v2' \
--header 'content-type: application/json' \
--data '{
    "auth_token": "{LEGACY_API_TOKEN}",
    "merchant_uuid": "{MERCHANT_ID}",
    "app_uuid": "{APP_ID}",
    "code_challenge": "{CODE_CHALLENGE}"
}'

{
    "authorization_code": "{AUTHORIZATION_CODE}",
    "expiration": 1678489882
}

Step 3: Request and receive an access_token and refresh_token pair

To exchange the authorization code for an expiring OAuth token:

1. Send a POST request to the /oauth/v2/token endpoint.
2. Do one of the following:
   1. For a high-trust app, include the parameters: client_id, client_secret, and code.
   2. For a low-trust app, if using PKCE, include the parameters: client_id, code, and code_verifier.

When the Clover server responds to the request, retrieve the expiring OAuth 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 token for high-trust app

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

Expiring OAuth token for low-trust app

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/v2/token' \
--header 'content-type: application/json' \
--data '{
    "client_id": "{APP_ID}",
    "code": "{AUTHORIZATION_CODE}",
    "code_verifier": "{CODE_VERIFIER}"
}'

{
"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