API Key Rotation

This quick guide introduces you to some best practices that you should employ when designing an API Key Rotation policy.


API key rotation is crucial for maintaining the security of your Marketplacer integrations by limiting the exposure and reducing the risk of unauthorised access. This guide outlines some suggested approaches when implementing an API key rotation policy.


API Keys in Marketplacer can be manually created either in:

  • The Operator Portal
  • The Seller Portal

While the process for creating keys in each portal is slightly different, (as well as the APIs they service), they share the same fundamental characteristics, and therefore you should ensure you develop a key rotation policy for both in-line with your own security policies and practices.

The remainder of this document covers some key points and considerations to take into account when developing your API Key Rotation policy.

Access to Keys

API keys can only be created by users that have the requisite permissions:

  • Operator Portal: Full Admin and Webmaster Roles only
  • Seller Portal: anyone with a user account
    • The “Allow API Access” feature also has to be enabled by the Operator

The first thing you may therefore want to consider is who should be permitted to create API keys from both an Operator and Seller perspective.

Additionally, you may want to restrict access to particular environments within Marketplacer, such as limiting a developers’ access to a sandbox or testing environment only, rather than production environments.

Key Rotation Schedule

The frequency with which you rotate keys is a major consideration, as you will want to ensure you are rotating keys in a manner that achieves the necessary level of security while allowing you to manage the rotation process in line with your organizational requirements. While we cannot advocate one particular schedule for all customers (without knowing their specific organizational requirements), we direct you to the following resources to assist with understanding industry practices:

Emergency Rotation

In case of a security incident, suspected compromise, or any other situation that may pose a security risk, API keys must be rotated immediately. Your incident response team should assess the situation and initiate key rotation immediately if necessary.

Key Rotation Process

The following is not intended to cover all matters you will need to consider, but rather aids in your consideration of steps in the process of rotating keys.

1. Reminder / Notification

Having established your rotation schedule, you need to ensure that you act in accordance with that schedule.

2. New key generation

Before rotating an API key, a new key must be generated using either the Operator or Seller portal. Again, only the relevant authorized persons should have access to do this.

3. Testing

Prior to updating keys, ensure that the new key has been tested to ensure that any API consumers that use that key will continue to work as expected.

4. Key update

Once the new key has been generated (and tested), update it in all relevant configurations, scripts, applications and systems that use API keys for authentication.

5. Delete the old key

Once you have established that the new key has been deployed and is working correctly, delete the old key. If you skip this step, any risks you are looking to mitigate via key rotations are still active.

HMAC for Mutations

If you are using HMAC for Mutations, the HMAC key is generated along-side the API Key. Therefore, if you undertake to rotate your API Keys, you will also need to ensure that you rotate the HMAC keys as well.