If your app uses a non-expiring auth token generated using the legacy v1/OAuth flow you need to migrate to using an expiring authentication token that includes an access_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 API token for a new access and refresh token pair:

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_verifierto generate thecode_challenge. For example, with the SHA-256 encryption, the code_challenge = SHA256(code_verifier).

Step 2: Request and receive 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 query parameters: merchant_ID, app_ID, legacy_API_token.
   2. For a low-trust app, if using PKCE, include the query parameters: merchant_ID, app_ID, legacy_API_token, 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 API token for high-trust app

{
    "merchant_uuid": "{MERCHANT_ID}",
    "app_uuid": "{APP_ID}",
    "auth_token": "{LEGACY_API_TOKEN}",
}

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

Expiring OAuth API token for low-trust app

{
    "merchant_uuid": "{MERCHANT_ID}",
    "app_uuid": "{APP_ID}",
    "auth_token": "{LEGACY_API_TOKEN}",
    "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 API 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 query parameters: client_id, client_secret, and auth_code.
   2. For a low-trust app, if using PKCE, include the query parameters: client_id, auth_code, and code_verifier.

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 for high-trust app

{
  "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 API token for low-trust app

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