Expiring OAuth Tokens: Securing Clover Merchant Data

Here at Clover, we like to keep it fresh, refreshed, that is, in how you access merchant data. With Clover, you are always up to date with the latest security measures with API's. With OAuth 2.0 came the use of bearer tokens, and we've decided to further secure merchant data by implementing expiring bearer, AKA access tokens.

Clover opted to implement expiring tokens in the unlikely case your app is compromised; we can assure merchants that the token used to access data will expire within minutes and, therefore, the hacker's access. Let's walk through how Clover uses OAuth. When a merchant selects and installs your app from the Clover App Market (in production environments), we use OAuth first to secure the communication between your app and the merchant and then give your app the necessary access to merchant data. As a developer, you will dynamically refresh the access token once the original expires in the backend.

Clover OAuth flow: The Access Token

The OAuth flow for new apps is as follows; your app requests merchant authorization from the Clover server. The Clover server responds with a one-time, app-specific code that your app will use to request an access token. The response will provide an access token, expiration time, refresh token, and the respective expiration time. Once your access token expires, you will call the refresh endpoint using your refresh token, and the Clover server will again provide you with a new access token. This cycle will repeat for as long as merchant data is required. See docs.clover.com for a recipe.

Legacy token migration

Apps with non-expiring tokens with legacy API tokens will exchange for expiring access and refresh token pair, just as new apps do. The migration flow follows; Your app calls POST /oauth/token/migrate_v2 to the Clover server. Clover responds with an authorization code, and the process is the same as new apps from here, pickup up at the POST /oauth/v2 token endpoint.

Request
POST /oauth/token/migrate_v2

Request Body
{
“merchant_uuid: “ {MERCHANT_ID} ”
“app_uuid”: “ {APP_ID} ”
“auth_token” :  “ {LEGACY_API_TOKEN} ”
“ code_challenge ” : “ {CODE_CHALLENGE} ”
}

Response
{
“authorization_code” : “ {AUTHORIZATION_CODE} ”
“expiration”: 1678489882
}

Possible errors and how to fix them

• 401 failed to validate code: In this event, you're likely using the v1 app code URL for the /v2/token endpoint. Be sure to use the updated v2 auth code URL: https://{clover_server}.clover.com/oauth/v2/authorize?client_id={app_id}&redirect_uri=http://{app_site_URL}
• CORS fetch error: This likely means you are making requests from the browser vs. a server. By design, Clover API calls can never originate from the browser to avoid exposing tokens/ keys to the web.
• Expiration time: The expiration dates are represented as Unix timestamps
• Sandbox vs. Prod: Our OAuth documentation is intended for use with the sandbox environment. To follow the OAuth flow for apps on the Clover App Market (in production environments), replace https://sandbox.dev.clover.com/ with the correct regional base URL in your requests:
• US and Canada: https://www.clover.com/
• Note: The new OAuth flow is only available in North America.

Wrapped Up

For North America in August 2023, Clover is implementing a new OAuth flow that requires expiring access tokens for new applications on the Clover App Market. Legacy apps will eventually migrate to the new OAuth flow in Q4 of 2023. Thankfully, other than Clover server URL, there is no difference in these tokens in Sandbox vs. Production. See our webinar on the Clover Platform Youtube channel and docs.clover.com for additional resources.