Generate an OAuth API token or `access_token`

Overview of the legacy OAuth and the v2/OAuth flow for Clover apps.

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 OAuth and the 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	Timeline	Description	Reference
Legacy OAuth flow	Apps created before October 2023	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 OAuth flow. To migrate from the legacy v1/OAuth flow to the v2/OAuth flow, see Migrate legacy OAuth API tokens to v2/OAuth expiring tokens.
v2/OAuth flow	New apps created after October 2023	New app integrations for merchants use the v2/OAuth flow. This flow generates an expiring token, which includes an `access_token` and `refresh_token` pair.	Generate expiring (access and refresh token) with the v2/OAuth flow.

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.

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 Token `access_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 token `refresh_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.

Watch video: Clover v2/OAuth expiring tokens

Watch	Learn
	In this video, learn: What are expiring tokens. How to generate access and refresh tokens. How to migrate an existing app to use expiring tokens. How to start the OAuth flow from the Merchant Dashboard left navigation app link. View or download: Clover expiring tokens slides

Watch

Learn

In this video, learn:

What are expiring tokens.
How to generate access and refresh tokens.
How to migrate an existing app to use expiring tokens.
How to start the OAuth flow from the Merchant Dashboard left navigation app link.

View or download: Clover expiring tokens slides

Get started

Use the v2/OAuth flow

Generate expiring (access and refresh) token with the v2/OAuth flow.

Use the refresh token

Generate a new access_token and refresh_token pair before the current one expires.

Learn about the legacy OAuth flow

Apps created before October 2023 use the legacy OAuth flow to generate an auth_token.

Migrate to the v2/OAuth flow

Migrate apps using the legacy OAuth flow to use an expiring authentication token that includes an access_token and refresh_token pair.

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