Generate OAuth expiring (access and refresh) token
Prerequisites and steps for generating an access_token
and refresh_token
pair using the v2/OAuth flow
All REST API endpoints require an OAuth-generated access_token
with specific permissions. Use the v2/OAuth flow to create an expiring authentication token, which includes an access_token
and a refresh_token
pair.
Prerequisites
For merchants in North America and Latin America, you can use the global developer platform.
- Create a global developer account.
- Manage test merchant accounts and information.
- Create your app in the sandbox environment.
- Configure settings and permissions that your app requires to access Clover merchant data.
- Required for the v2/OAuth flow—Set the Alternate Launch Path to redirect merchants to install and launch your app from the Clover App Market. See Set app link (URL) and CORS domain.
For merchants in Europe, you can use the developer platform and follow the steps to Get started with the developer platform.

App Settings on the Developer Dashboard: Edit REST Configuration page
Steps
The Clover v2/OAuth flow starts when the merchant selects your app directly from the Clover App Market or on the Merchant Dashboard > More Tools > Clover App Market page. Clover redirects the merchant to your app with the merchantId included in the Redirect URI as a query parameter. From there, your app must call the /oauth/v2/authorize
endpoint to initiate the v2/OAuth flow and get an access_token
and refresh_token
pair.
If a merchant accesses the app from your website instead of installing and connecting with it from the Clover App Market, your app needs to redirect the merchant to the Clover App Market page to install the app from there. The Alternate Launch Path is used in this case.
To generate an expiring access and refresh token pair:
-
Log in to the Global Developer Dashboard.
-
Navigate to the Merchant Dashboard for your test merchant.
-
From the left navigation menu, click More, and then select your app on the Clover App Market page.
-
Click Connect to install your app for the test merchant.
From here:
-
For merchant authorization, Clover redirects the merchant to the location specified in the Alternate Launch Path field, and the app calls
/oauth/v2/authorize
with the authorization codeauth_code
as a query param to initiate OAuth.`https://www.example.com/oauth_callback?code={AUTHORIZATION_CODE}&merchant_id={MERCHANT_ID}`
-
For token exchange, your app makes a POST request with the
client_id
,client_secret
, andauthorization_code
to/oauth/v2/token
. The response provides anaccess_token
andrefresh_token
pair that displays on the OAuth Process Results page of your app.Sample: Access and Refresh token pair
-
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
}
Generate a new OAuth expiring token with a refresh token
In the v2/OAuth flow, an expiring authentication token consisting of an access_token
and refresh_token
pair is generated. 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.
For information, see Use refresh token to generate new expiring token.
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.
Request path | Sandbox URL | Production URL (North America) |
---|---|---|
/oauth/v2/authorize | apisandbox.dev.clover.com | www.clover.com |
/oauth/v2/token | apisandbox.dev.clover.com | api.clover.com |
/oauth/v2/refresh | apisandbox.dev.clover.com | api.clover.com |
/oauth/token/migrate_v2 | apisandbox.dev.clover.com | api.clover.com |
Related topics
- Authenticate with v2/OAuth flow
- Blog: Expiring OAuth Tokens: Securing Clover Merchant Data
- Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys
Updated about 23 hours ago