Refresh access tokens
To prevent your app from becoming unauthorized, your app uses the refresh token. The auth code flow generates new access and refresh tokens before the current tokens expire.
IMPORTANT
Limits apply to the number of refresh tokens that the auth code flow can create per merchant-app combination. If an app exceeds the limit, older tokens become invalid.
You can only use refresh tokens once, and they become invalid after use. A new refresh token is generated during the refresh process and returned in the response body. When you generate new access and refresh tokens, use the new refresh token in the request.
Generate new access and refresh tokens
IMPORTANT
The following values for access and refresh tokens are dynamic and can change:
- Token expiration displays in the response body. Tokens created later can have different durations until they expire.
- Token lengths are not fixed.
Do not hard code access and refresh token expirations or lengths so that you can handle any future updates.
To generate new access and refresh tokens:
Step | Who/what | What |
---|---|---|
1 | Developer app | Send a POST request to the /oauth/v2/refresh endpoint. Include the client ID and refresh token from the auth code flow response.Request POST /oauth/v2/refresh Request body { "client_id": "{APP_ID}", "refresh_token": "{REFRESH_TOKEN}"} Sample response body { "access_token": "{ACCESS_TOKEN}", "access_token_expiration": 1709498373, "refresh_token": "{REFRESH_TOKEN}", "refresh_token_expiration": 1741034373} Note: The response body indicates when the access and refresh tokens expire. The expiration dates are represented as Unix timestamps. |
Bypass refresh token creation in the OAuth flow
Clover limits the number of active refresh tokens that an application can have for each merchant. In some scenarios, a refresh token is not needed:
- Frontend apps that use OAuth to authenticate users to their own apps often don’t need a refresh token.
- Some apps 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.
Generating a refresh token in such cases may cause the app to reach the limit unnecessarily. Use the no_refresh_token
flag on the OAuth Authorize endpoint to bypass the refresh token creation.
To bypass generating a refresh token for your app:
Step | Who/what | What |
---|---|---|
1 | Developer app | Send a POST request to the /oauth/v2/token endpoint. Set the no_refresh_token flag to true.Request POST /oauth/v2/token?no_refresh_token=true Request body { "code": "{AUTHORIZATION_CODE}", "client_id": "{APP_ID}", "client_secret": "{APP_SECRET}"} Sample response body { "access_token": "{ACCESS_TOKEN}", "access_token_expiration": 1709498373,} A refresh token is not returned. Note: The response body indicates when the access and refresh tokens expire. The expiration dates are represented as Unix timestamps. |
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 | sandbox.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 |
Updated 15 days ago