Skip to main content

API Key Best Practices

Updated

Table of Contents

  1. Overview
  2. Basic API Key Security
  3. Associated Account Security
  4. Periodic Rotation
  5. IP Restrictions

 

Overview

Due to infrequent direct usage, API keys are a commonly neglected component of account security. While that minimized “hands-on” time reduces the exposure to common account security risks (e.g. Phishing), these keys still represent an important element to be maintained as a part of good account security hygiene.

This article provides some best practice guidance for managing API keys and accounts they are tied with.

 

Basic API Key Security

API keys behave similarly to passwords in the Gateway. They are used to login to an associated account that allows transaction and account actions, many just like with a username and password combination.

These keys act as account credentials and fundamental security practices should be followed to secure any API keys associated with your account, including:

  • Limit knowledge and access to plaintext keys - Only Gateway administrators and those with a specific need to see the keys should be granted access.
  • Reduce storage locations of cleartext API keys - The API key should only be stored on the application server using it. In the event an API key must be recovered, API keys are always visible to Gateway administrators.
  • Communicate API keys using secure methods - If you must share API keys with someone who is configuring an application on your behalf, provide the information in a secure method. Communicate using encrypted email or chat services that securely purge the information after a preset amount of time, or deliver using a split-knowledge method (e.g. Deliver part of the key in an email, and the last part over the phone).
  • Use unique API keys per system function - Generate separate API keys to be used for each unique function your application conducts (e.g. account management, sale, void, etc…). In the event the security of one key is compromised, the separate keys will help to minimize the extent of negative impacts.

 

Associated Account Security

Before an API key can be created on the Gateway, a specific user account must be selected to be tied to that key. As the Gateway’s API has many powerful features available, accounts these keys are tied to must also be carefully considered.

When configuring your API keys, here are a few security elements to consider surrounding the accounts:

  • Use a dedicated “service” account - Instead of adding an API key to a user’s account, create a Gateway user specifically for your API keys that have similar functions. This account should not be used by a general user, but only for systematic API interactions.
  • Do not use administrative accounts - Affiliate accounts with the “O” permission and Merchant accounts with the “A” permission are administrative and provide a wide amount of access. These administrative functions are not typically needed to support applications.
  • Limit permissions to only those required - The account used for API access should only be granted the minimum permissions required for correct application functionality. For example, if you are using the API to generate reports, the account used would not need access to manage merchant or affiliate accounts.

 

Periodic Rotation

Since API keys need to be stored, passed around, and leveraged in the development of solutions that interact with the Gateway, there are still opportunities for these secret API keys to be leaked.

As a general precaution, the API keys associated with your account(s) should be rotated/re-generated on a periodic rolling basis. While specific security needs and risks will vary for your organization, it’s generally recommended to re-create the API keys on an annual basis.

To ease the transition process, you can generate a new API key that is valid at the same time as the old API key, transition your application to the new API key, and then delete the old API key after testing connections.

 

IP Restrictions

IP Restrictions, also commonly known as IP Address Whitelisting, is another security feature available on all Gateway accounts. This allows you to specify only the specific IP addresses permitted to log in to your account’s Control Panel and API.

Accounts leveraging the API are typically used by application servers with static/non-changing public IP addresses. If your application is set up this way, you can set IP Restrictions for all of your approved IP addresses and minimize the risk of unauthorized individuals accessing your account (even if they somehow obtain your API key).

For more information on how to enable and use IP Restrictions, download the guides below. These documents may also be used as brandable guides to share with your merchants and/or sub-affiliates on how to set up IP Restrictions within their Gateway account.