Migrate legacy OAuth API tokens to v2/OAuth expiring tokens
North America—United States and Canada
If your app uses a non-expiring auth token generated using the legacy v1/OAuth flow you need to migrate to using an expiring authentication token that includes an access_token and refresh_token pair. The token migration flow includes the option to use Proof key for code exchange (PKCE) for low-trust apps.
Token migration flow with PKCE option
Token migration flow
Migrate legacy tokens
To exchange a legacy OAuth API token for a new access and refresh token pair:
| Step | Who/what | What |
|---|---|---|
| 1. | Developer app | If using PKCE, generate a code_verifier and code_challenge using the method of your choice. |
| 2. | Developer app | Request an authorization code. Send a POST request to /oauth/token/migrate_v2. Include the merchant ID, app ID, legacy API token, and if using PKCE, code challenge in the request body.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}"} |
| 3. | Clover backend | Return authorization code. Sample response body { "authorization_code": "{AUTHORIZATION_CODE}", "expiration": 1678489882} |
| 4. | Developer app | Request an access token pair. Send a POST request to /oauth/v2/token. Include the client ID, client secret (if a high trust app), auth code, and if using PKCE, code verifier in the request body.Request POST /oauth/v2/token Request body { "client_id": "{APP_ID}" "client_secret": "{APP_SECRET}", -> If a high trust app "code": "{AUTHORIZATION_CODE}", "code_verifier": "{CODE_VERIFIER}" -> If using PKCE} |
| 5. | Clover backend | Return new access and refresh tokens. Sample response body { "access_token": "{ACCESS_TOKEN}", "access_token_expiration": 1677875430, "refresh_token": "{REFRESH_TOKEN}", "refresh_token_expiration": 1709497830} 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 |
Related topics
Updated 13 days ago