--- updatedAt: 2026-06-17T21:00:21.000Z agentTools: projectIndex: https://docs.clover.com/dev/llms.txt --- # Use refresh token to generate new expiring token [block:html] { "html": "" } [/block] # 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. # Key features of expiring tokens Key features of access and refresh tokens are: * **Limitations on the number of refresh tokens**—Clover limits the number of active refresh tokens an app can have for each merchant. If an app exceeds the limit, prior tokens become invalid. * **Limitations on refresh token usage**—Refresh token is for single use and becomes invalid immediately after a new `access_token` and `refresh_token` pair is generated using the `/oauth/v2/refresh` endpoint. * **Dynamic expiration dates and length**—You should not hard code access and refresh token expirations or lengths but handle them dynamically in your app: * Token expiration date is based on the time the token is generated; hence, tokens created over a period of time have different expiration dates. The format of the expiration dates is Unix timestamp. * Token length is not fixed. *** # 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. [block:parameters] { "data": { "h-0": "Request path", "h-1": "Sandbox URL", "h-2": "Production URL \nNorth America", "h-3": "Production URL \nEurope", "h-4": "Production URL \nLatin America", "0-0": "/oauth/v2/authorize", "0-1": "sandbox.dev.clover.com", "0-2": "www\\.clover\\.com", "0-3": "www\\.eu\\.clover\\.com", "0-4": "www\\.la\\.clover\\.com", "1-0": "/oauth/v2/token", "1-1": "apisandbox.dev.clover.com", "1-2": "api.clover.com", "1-3": "api.eu.clover.com", "1-4": "api.la.clover.com", "2-0": "/oauth/v2/refresh", "2-1": "apisandbox.dev.clover.com", "2-2": "api.clover.com", "2-3": "api.eu.clover.com", "2-4": "api.la.clover.com", "3-0": "/oauth/token/migrate_v2", "3-1": "apisandbox.dev.clover.com", "3-2": "api.clover.com", "3-3": "api.eu.clover.com", "3-4": "api.la.clover.com" }, "cols": 5, "rows": 4, "align": [ "left", "left", "left", "left", "left" ] } [/block] *** # 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](https://docs.clover.com/dev/docs/generate-oauth-expiring-access-and-refresh-token). 1. Install the app and receive authorization information from the `/oauth/v2/authorize` endpoint. 2. 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 1. Send a POST request to the `/oauth/v2/refresh` endpoint. 2. 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](https://docs.clover.com/dev/docs/use-refresh-token-to-generate-new-expiring-token#prerequisite). ### Request and Response example—Generate new access and refresh tokens ```curl Request 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}" } ``` ```json Response { "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: 1. Install the app and receive authorization information from the `/oauth/v2/authorize` endpoint. 2. Send a POST request to the `/oauth/v2/token` endpoint with the following parameters: `client_id`, `client_secret`, and `authorization_code`. 3. Set the `no_refresh_token` parameter to true. ### Request and Response example—No refresh token ```curl Request 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}" }' ``` ```json Response { "access_token": "{ACCESS_TOKEN}", "access_token_expiration": 1709498373, } ``` The response returns only an access token, along with the expiration date, in Unix timestamp format. *** # Related topics * Generate OAuth expiring (access and refresh) token * Blog: Expiring OAuth Tokens: Securing Clover Merchant Data * Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys