Generate an OAuth API token or `access_token`
Overview of the legacy v1/OAuth and new v2/OAuth flows
North America—US and Canada
Global developer platform
Overview
To secure communication between your app and the merchant, you need an OAuth API token. The OAuth API token, also known as the access_token is required to:
- Complete the Ecommerce API authorization flow that grants your app the necessary permissions to access the merchant's data.
- Generate an Ecommerce API key or
apiAccessKey. This is also known as the PAKMS key, as it is generated from the Public Access Key Management Service (PAKMS) using the Ecommerce - PAKMS Service API. The Ecommerce API key identifies the merchant who is tokenizing customers' cards. You can use the same static Ecommerce API key to tokenize multiple cards for that merchant.
OAuth flows: Legacy v1/OAuth and the new v2/OAuth flow
All Ecommerce API endpoints require an OAuth-generated access_token with specific permissions. There are two methods to generate this access_token:
| OAuth flow | Region | Time | Description | Reference |
|---|---|---|---|---|
| v1/OAuth flow | All regions | Apps created before August 2024 | App integrations not yet transitioned to expiring tokens use the legacy v1/OAuth flow to generate an OAuth API token. This access_token is also referred to as an auth_token. | Generate OAuth API token with the legacy v1/OAuth flow. |
| v2/OAuth flow | North America: United States and Canada | New apps created after August 2024 | New app integrations created for merchants in North America use the v2/OAuth flow is used. This flow generates an expiring token, which includes an access_token and refresh_token pair. | Generate OAuth expiring access and refresh token. |
NOTE
To migrate from the legacy v1/OAuth flow to the v2/OAuth flow, see Migrate legacy OAuth API tokens to v2/OAuth expiring tokens.
To learn more about the v2/OAuth flow and expiring tokens, see:
Terminology
The following terms are used in the OAuth flows to generate an OAuth token:
| Term | Description |
|---|---|
| Client ID or App ID | App ID or Client ID that uniquely identifies an app on Clover App Market. This ID is also used to confirm that your app is participating in the OAuth 2.0 flow. |
| Client Secret or App Secret | App Secret or Client Secret is a secret key that Clover assigns to your app. Do not share the Client Secret key publicly. Note: Both the App ID and App Secret are automatically assigned when you create an app. You can view the App ID and App Secret on the App name - App Settings page. Both these values are required for you to authenticate your app with the Clover server and make authorized and authenticated requests to Clover merchant data. |
| Merchant ID | Merchant identifier or merchantId that uniquely identifies Clover merchants, including test merchants, on the Clover platform. See Locate the test merchant identifier (merchantId). |
| Merchant | Clover merchants can be either unauthorized or authorized to connect to your app. - An unauthorized merchant wants access to your app but has not logged in to their Clover merchant account. Your app redirects this merchant to log in to their merchant account using the following URL format: https://sandbox.dev.clover.com/oauth/authorize?client_id={APP_ID}- An authorized merchant has logged in to their Clover merchant account. The Clover server redirects the merchant to your app with an authorization code using the following URL format: -- In the legacy v1/OAuth flow: https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE}-- In the v2/OAuth flow: https://www.example.com/oauth_callback?code={AUTHORIZATION_CODE}&merchant_id={MERCHANT_ID} |
| Authorization Code | Clover redirects an authorized merchant logged into the Merchant Dashboard to your app along with an authorization code. The Clover server provides this temporary auth_code after the merchant is authenticated. This auth_code is exchanged for an access token during the OAuth flow. |
| Site URL | Link or URL for your app that you set on the Edit REST Configuration page for web apps. Your merchant is redirected to this link after they install your app and launch it from the Merchant Dashboard. The Clover server sends authenticated merchants to the Site URL through the/oauth/authorize flow, where they can log in or select their merchant account. |
| Alternate Launch Path | Alternate launch path link or URL for your app that you set on the Edit REST Configuration page for web apps. Your merchant is redirected to this link after they install and launch the app from the Merchant Dashboard. This alternate path URL is required for the oauth/v2/authorize flow, as it:- Uses the expiring tokens to authenticate with APIs. - Sends the merchant directly to your app and initiates the OAuth flow. |
OAuth or API Tokenaccess_token | Your app uses the Authorization Code, Client ID, and Client Secret to negotiate with the Clover server for an OAuth API token or access_token. With the API token, your app can make REST API calls and access merchant data. See Use Clover REST API.Access token generated with the oauth/v2/authorize flow expires after some time and is generated in a pair with a refresh token. This v2/OAuth flow-generated access and refresh token pair is known as an expiring token. |
Refresh tokenrefresh_token | One-time-use token that is used to generate another access token when it expires. Refresh tokens are valid for a longer period than the access token but also expire. Clover limits the number of active refresh tokens an app can have for each merchant. |
| Expiring token | An access_token and refresh_token pair is called an expiring token. |
Get started
For prerequisite and steps to generate an OAuth API token, see:
- Generate OAuth API token with the legacy OAuth flow
- Generate OAuth expiring access and refresh token
Related topics
Updated 12 days ago