Low trust apps—Auth code flow with PKCE
North America—United States and Canada
If your app is a mobile, single-page, or native desktop application, it can not safely store the client's secret and is a low trust app. Therefore, the app must use the auth flow with a proof key for code exchange (PKCE), as shown in the diagram.
Auth code flow with PKCE for low trust apps
Auth code flow with PKCE for low trust apps
Generate an access and refresh token pair using PKCE
IMPORTANT
The following values for access and refresh tokens are dynamic and can change:
- Token expiration displays in the response body. Tokens created later can have different durations until they expire.
- Token lengths are not fixed.
Do not hard code access and refresh token expirations or lengths so that you can handle any future updates.
To create an access and refresh token pair using PKCE:
| Step | Who/what | What |
|---|---|---|
| 1 | Developer app | Generate a code_verifier and code_challenge as shown in the flow diagram. The code_verifier must be a random string value, and the code_challenge must be a SHA256 hash of the code_verifier. |
| 2 | Developer app | Redirect the merchant to /oauth/v2/authorize with the code_challenge. |
| 3 | Merchant | Log in to the merchant Clover account and install the developer’s app from the Clover App Market. By installing the app, the merchant authorizes the app to access the merchant’s information that the app requires. |
| 4 | Clover backend | Redirect the merchant to the developer’s app with an authorization code. Example: https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE} |
| 5 | Developer app | Request an access and refresh token pair. Send a POST request to /oauth/v2/token. Include the client ID, auth code, and code verifier in the request body.Request POST /oauth/v2/token Request body { "client_id": "{APP_ID}", "code": "{AUTHORIZATION_CODE}", "code_verifier": "{CODE_VERIFIER}"`} |
| 6 | Clover backend | Return an access and refresh token pair. Sample response body { "access_token": "{ACCESS_TOKEN}", "access_token_expiration": 1677875430, "refresh_token": "{REFRESH_TOKEN}", "refresh_token_expiration": 1709497830} Note: The response body indicates when the access and refresh tokens expire. The expiration dates are represented as Unix timestamps. |
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 | sandbox.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 |
Updated 15 days ago
Related topics