Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys

In the real world, you probably have more than one key — maybe keys for your home, your car, your work, and a gym locker. It can be hard to keep them organized. Sometimes you forget which key opens the door if it isn’t labeled correctly — and scrambling through keys is never fun.

The same concept can apply when developing applications for Clover. Clover applications can have multiple keys, especially if you’re working with the Ecommerce API. This blog can help you avoid scrambling through your (digital) keys.

During your development journey with Clover you are given authorization keys, tokens, and parameter keys. You may even generate your own:

• OAuth token/Access token/auth_token
• PAKMS (Public Access Key Management Service) key
• App Secret / Client Secret
• Idempotency key

Let’s go through each type, one by one, to get a sense of how these keys are used and how they interact.

Authorization Header Keys

Auth Token

The most important key is your Auth token or access_token. This is a highly confidential key. You can read more about this token in our Clover Docs: Using OAuth 2.0. The Auth token (sometimes called the auth_token or access_token) is used in the authorization bearer header to authenticate the majority of Clover API calls. This token is given to you after going through a proper OAuth 2.0 flow for a merchant who downloaded and opened your app. Here are some key things to remember with this token:

• It is the main authorization to allow you to make successful REST API requests to Clover.
• It ties the developer app to the merchant and is unique for each merchant.
• It is received through an OAuth process that requires your Client ID, Client Secret, and one-time Authorization code.

In order to run OAuth to receive your application’s auth token for each merchant, you need the following details.

• Client ID: the UUID that uniquely identifies your app. This ID is auto-generated by Clover. This ID is called your App ID in developer dashboard.
• Client Secret: the secret key that is assigned to your app by Clover. This ID is called your App Secret in developer dashboard. App Secrets can only be used with their corresponding app, so make sure to track the connection between the App ID and its secret.
• Authorization Code: A code sent back to the app once a merchant approves (authorizes) the app to have permissions to access their account. This code is unique to every merchant for every app they have downloaded and will change each time you call OAuth.

Auth tokens are generated for each merchant and can only be used for that merchant, as illustrated in the following diagram:

Client Secret/ App Secret

The Client Secret, or App Secret, is an auth key as well. Clover automatically provides this key to you, along with an App ID, when you create an app.

A word of caution — The App Secret should only be used by a backend server and not the front end of the app itself. If the App Secret is exposed to the front end, a malicious actor could easily find and use it.

The Client Secret or App Secret replaces the Auth Token in only two types of calls:

• App notifications
• Billing

App notifications allow you to send Android messages to the merchant on an app or device level. For example, your app handles online orders and an order is sent to Clover. You may want to send an on-device notification to the merchant that an order is received. You can find an example of the request at Sending app notifications.

Billing endpoints allows you to review the app billing a merchant has subscribed to, and create/modify metered events. For example, you may want to build a billing page for your app that displays all of the metered events for that merchant to review. You can also manage your pricing tiers from the Clover Developer Dashboard, more information on setting up pricing tiers is available in Setting up pricing tiers.

Header Keys

Idempotency-Key

In math and computer science, idempotency refers to operations that can be applied multiple times without changing the result beyond the initial application. This key is used as a safeguard against duplicate transactions. With this key, you can avoid re-running the same transaction multiple times for the same card and customer during a system outage. The ‘idempotency-key’ is used as a header in payments/refund requests calls.

Clover does not supply this key. And although they are not required, we recommend you create idempotency keys for your ecommerce app or semi-integration. We recommended you use keys consisting of at least 13 alphanumeric characters.

The following is an example of an idempotency-key being used to create an Ecomm charge:

Idempotency keys are also useful for tracking down potential issues with order and payment reconciliations. Every new charge and change to a charge should have a different idempotency-key to help you track where an error may have occurred.

A great flow chart is available on our Clover Docs: Tracking Transactions with Idempotency Keys

PAKMS

PAKMS is a key management service that makes it easy for you to control and create protected Clover card tokens. This key is generated from an API call with auth_token as an authentication bearer header. PAKMS is tightly associated with the developer app and the merchant. The same key can be used to tokenize multiple cards for that merchant.

This key is crucial for making Ecomm API payments and is the second step in tokenizing a card number. This key is static for the merchant. You don’t need to call the endpoint every time you tokenize a card.

GET PAKMS Example

Output: apiAccessKey

{
  "active": true,
  "apiAccessKey": "string",
  "createdTime": 0,
  "developerAppUuid": "string",
  "merchantUuid": "string",
  "tokenAssociationGroupUuid": "string",
  "modifiedTime": 0
}

An apiAccessKey is returned when you call to GET a PAKMS key, and you can use it as header to tokenize a card. When you tokenize a card with PAKMS, the header key name will be apiKey. Here’s an example of a post using the PAKMS key.

PAKMS used to token a card

Key Interactions

With all those definitions out of the way, we made a keychain to map out the key usage. This diagram shows you the order of keys and when to use them. Again, most API requests are authenticated by your OAuth token in the authentication bearer header.

*This is a snippet of the keys and it does not show all of Clover endpoints.

Most Important Rule: NEVER SHARE YOUR KEYS PUBLICLY

Now that you have an understanding of the Clover digital keys, always remember to never share your keys publicly. If you are storing a key anywhere (and by that we mean a backend database, because that’s where they’re safest), it’s a best practice to store it encrypted rather than in plain text.

Sharing your keys can release chaos in the app world.

Okay, a little dramatic…Still, sharing your keys can leak important information like personal identifiable information (PII) data, sensitive PII data, and security details. However, if you inadvertently share your keys publicly, don’t worry because the Key Masters at Clover Developer Relations can intervene as a last resort.

If you have any questions or concerns you can always reach out to us at developer-relations@devrel.clover.com, and we have 24/7 Community.

Don’t forget to subscribe to our Youtube channel and join our Developer Newsletter to get the latest and greatest updates.