Understand the Clover v2/OAuth flow

North America—United States and Canada

This topic explains how Clover implements OAuth principles in its application authentication paradigm. The Clover v2/OAuth flow is only available in North America.

Auth code acquisition flows

Clover apps use the following authorization token acquisition flows:

Auth flow	Description
Implicit flow	Also called response type token, this is the least secure authorization flow. Implicit flow is a simplified auth flow that cannot securely store a client secret. The `access_token` is returned immediately without an extra authorization code exchange step. Implicit flow was previously recommended for native and JavaScript apps that can not securely store a client secret. 🚧 Important: Clover plans to deprecate the response type token (implicit) flow. If your app uses response type tokens, migrate your app to use the auth code flow with PKCE. See Migrate legacy OAuth API tokens to v2/OAuth expiring tokens for more information.
Authorization code flow	Used by high trust apps to exchange an authorization code for an `access_token`. After the redirect URL returns the merchant to the application, the app receives the authorization code from the URL and uses it to request an `access_token`.
Authorization code flow with proof key for code exchange (PKCE)	Required for all low-trust apps that can not securely store a client secret, such as standalone mobile, desktop, and single-page applications.

Low-trust and high-trust apps

App security	Description	Reference
High-trust apps	Securely store and use a Client Secret (App Secret). High-trust apps can use the standard auth code flow to generate auth tokens.	High trust apps—Auth code flow
Low-trust apps	Do not securely store and use a client secret (app secret)—such as mobile, single-page, and native desktop applications. Low-trust apps use the response type token (implicit) auth code flow. Clover now requires that low trust apps use the auth code flow with PKCE. If your app uses the implicit flow and is considered to be a low-trust app, migrate your app to use the auth code flow with PKCE.	Low trust apps—Auth code flow with PKCE

Proof key for code exchange (PKCE)

Proof Key for Code Exchange (PKCE) is an extension to the OAuth 2.0 authorization code flow designed to enhance security, especially for public clients like mobile and single-page applications that cannot securely store the Client Secret. PKCE ensures that even if an authorization code is intercepted, it cannot be exchanged for tokens without the original code_verifier.

Terminology

PKCE uses the following parameters in the app to remove the need to pass the Client Secret:

Term	Description
Code verifier `code_verifier`	Unique random string that the app creates for every authorization request.
Code challenge `code_challenge`	App hashes the code verifier, resulting in the code challenge. Clover currently supports SHA256 (secure hash algorithm 256 bit) to one-way hash the code verifier. Other algorithms may be added in the future.

OAuth flow with PKCE

The OAuth flow with PKCE is as follows:

Generate code verifier and code challenge—The app generates a random string called the code_verifier and then creates a code_challenge by hashing the code_verifier using SHA256.
Authorization request—The app redirects the user to the authorization server with the code_challenge included in the request.
User authentication—The merchant logs in and authorizes the app to access their data.
Authorization code—The authorization server redirects the user back to the client app with an authorization code.
Token request—The app sends a request to the token endpoint, including the authorization code and the original code_verifier.
Token response—The authorization server verifies the code_verifier against the code_challenge and, if they match, issues an access_token and a refresh_token to the app.

Compare: Legacy response type token (implicit) flow with PKCE flow

Comparing the implicit flow and auth code flow with PKCE illustrates the added security steps in the auth code flow with PKCE.

Implicit flow compared to auth code flow with PKCE