Authenticate with OAuth—Canada and US
All REST API endpoints require an OAuth-generated access_token with specific permissions. The v2/OAuth flow is used for apps created for Clover merchants in North America—the United States, and Canada. This flow generates expiring tokens, which include an access_token and refresh_token pair.
Before you begin
Clover has introduced expiring tokens that are generated using a new v2/OAuth flow for apps in the United States and Canada. In this context, note the following:
- If you create apps for Europe or Latin America, use the v1/OAuth flow for your apps. See Authenticate with OAuth—Europe and Latin America.
- If you create apps for North America—the United States and Canada, use the instructions in this topic to create expiring authentication tokens with an
access_tokenandrefresh_tokenpair.
Why use OAuth?
OAuth is the industry-standard protocol for online authorization. Due to the sensitivity of merchant data, Clover has implemented the OAuth 2.0 security framework.
When a merchant selects and installs your app from the Clover App Market, Clover uses OAuth to secure the communication between your app and the merchant and to grant your app the necessary access to merchant data. Your app may need to access data about Clover merchants, such as their order history or current inventory, using the Clover REST API.
For more information, see Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys.
Watch video: Clover v2/OAuth expiring tokens
| Watch | Learn |
|---|---|
|
|
In this video, learn:
View or download: Clover expiring tokens slides |
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://apisandbox.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 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 (URL) for your app that you set on the Edit REST Configuration page for web apps. After a merchant installs your app and launches it from the Merchant Dashboard, they are redirected to the Site URL. 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. To override the post-authorization landing page, you can include the redirect_uri parameter in the OAuth authorization request. |
| Alternate Launch Path | Link (URL) or subpath for your app that you set on the Edit REST Configuration page for web apps. When a merchant accesses your app without installing it, the app redirects the merchant to this Alternate Launch Path, which then directs them to the Clover App Market to initiate the v2/OAuth flow. This Alternate Launch Path URL is required for the /oauth/v2/authorize flow, as it uses expiring tokens to authenticate with APIs, ensuring the merchant is properly authenticated and connected to your app. |
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 | Single-use token that is used to generate another access_token and refresh_token pair from the oauth/v2/refresh endpoint. 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. |
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 | apisandbox.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 |
Understand the v2/OAuth flow
If you create apps for North America—the United States and Canada, use the following list of contents to understand the v2/OAuth flow to create expiring authentication tokens:
- Clover v2/OAuth flow overview
- Auth code flow for high-trust apps
- Auth code flow for low-trust apps
- Initiate OAuth flow from the Clover App Market app selection
Generate expiring authentication tokens with the OAuth flow
For steps on how to generate the access_token and refresh_token pair and generate a new refresh token before the current token pair expires, see:
- Generate OAuth expiring (access and refresh) token
- Use refresh token to generate new expiring token
- Migrate legacy OAuth API tokens to v2/OAuth expiring tokens
Related topics
Updated 11 days ago