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 flowDescription
Implicit flowAlso 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 securityDescriptionReference
High-trust appsSecurely 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 appsDo 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.

Important! 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, such as 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:

TermDescription
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:

  1. 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.
  2. Authorization request—The app redirects the user to the authorization server with the code_challenge included in the request.
  3. User authentication—The merchant logs in and authorizes the app to access their data.
  4. Authorization code—The authorization server redirects the user back to the client app with an authorization code.
  5. Token request—The app sends a request to the token endpoint, including the authorization code and the original code_verifier.
  6. 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.

For details, see Low-trust apps—Auth code flow with PKCE.

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

Implicit flow compared to auth code flow with PKCE

Related topics