High trust apps—Auth code flow
North America—United States and Canada
High trust apps securely store and use a client secret (app secret), as shown in the diagram.
Auth code flow for high trust apps
Auth code flow for high trust apps
Generate 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 an access and refresh token pair:
| Step | Who/what | What |
|---|---|---|
| 1 | Merchant | Log in to the merchant Clover account and install the developer’s app from the Clover App Market. By installing the app, the merchant authorizes the app to access the merchant’s information that the app requires. |
| 2 | Clover UI | Redirect the merchant to the developer’s app with an authorization code. Example: https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE}NOTE: If the merchant is not logged in to their Clover merchant account and they try to access to your app, Clover redirects the merchant to log in to their merchant account and back to your app. Example: https://sandbox.dev.clover.com/oauth/v2/authorize?client_id={APP_ID}&redirect_uri={CLIENT_REDIRECT_URL} |
| 3 | Developer app | Request an access- and refresh-token pair. Send a POST request to /oauth/v2/token. Include the client ID, client secret, and auth code in the request body.Request POST /oauth/v2/token Query parameter—Optional If you do not need a refresh token, set the query parameter no_refresh_token to true in the request:/oauth/v2/token?no_refresh_token=trueSee When refresh tokens are not needed for more information. Request body { "client_id": "{APP_ID}" "client_secret": "{APP_SECRET}", "code": "{AUTHORIZATION_CODE}"} |
| 4 | Clover backend | Return an access and refresh token pair. Sample response body { "access_token": "{ACCESS_TOKEN}", "access_token_expiration": 1677875430, "refresh_token": "{REFRESH_TOKEN}", "refresh_token_expiration": 1709497830} 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