Skip to main content

API key management

In this section:

Keeping your API keys secure

When you use API keys in your applications, take care to keep them secure. Publicly exposing your credentials can result in your account being compromised, which could lead to unexpected charges on your account. To help keep your API keys secure, we recommend these best practices:

Store API keys / secrets safely

  • Do not embed API keys / secrets directly in code.

  • Do not store API keys / secrets in files inside your application, including the application’s source tree.

  • If you do accidentally commit an API key / secrets to version control, revoke the API key immediately and generate a new one.

  • Ensure API keys / secrets do not appear in URLs or anywhere that can be captured in web server logs.

  • Review your code carefully and ensure it doesn’t contain API keys / secrets or any other private information before publicly releasing it.

  • Put the configuration file containing the API keys / secrets in the revision control ignore (e.g. .gitignore). This prevents accidentally committing them in the future.

Limit the usage of API keys / secrets

  • Restrict your API keys / secrets to be used by only the IP addresses, referrer URLs, and mobile apps that need them.

  • Don't share your API keys / secrets with different applications. If more than one application uses the same API, register each application to get a new set of API keys / secrets.

Update API keys / secrets

  • Delete unneeded API keys / secrets.

  • Update (rotate) your API keys / secrets periodically.

Regular key rotation

Changing access keys (which consist of an access key ID and a secret access key) on a regular schedule is a well-known security best practice because it shortens the period an access key is active and therefore reduces the business impact if they are compromised. Having an established process that is run regularly also ensures the operational steps around key rotation are verified, so changing a key is never a scary step.

To rotate access keys, you should follow these steps:

  1. Create a second access key in addition to the one in use.

  2. Update all your applications to use the new access key and validate that the applications are working.

  3. Change the state of the previous access key to inactive.

  4. Validate that your applications are still working as expected.

  5. Delete the inactive access key.

Key rotation example

Here’s an example of the key rotation steps listed above.

Caution

Because keys are considered sensitive information, you should perform all of these commands only on a trusted computer.

  1. Create a second access key

    Create a new (second) access key for your integration system by contacting your Customer Success Manager or Customer Operations Manager.

  2. Distribute your access key to all instances of your applications

    After creating the new key, you will distribute it and instruct your application to transition to using it. Before moving on to the next step ensure that all instances of your application are indeed using it and that they function correctly.

  3. Change the state of the previous access key to inactive

    Contact your Customer Success Manager or Customer Operations Manager about disabling the old access key. To verify that the key has been disabled refer to its status shown next to it in the main API key list.

  4. Validate that your applications are still working as expected

    Once the key has been marked inactive, it cannot be used for authenticating Controlant Integration API calls; therefore, you should verify at this point that your application still works.

    That’s why we just disabled the old access key first: if something were to go wrong, you could quickly re-enable the previous access key using the h update-access-key command.

  5. Delete the inactive access key

    The last step is deleting the inactive access key by by contacting your Customer Success Manager or Customer Operations Manager.

    Note

    Deleting a key – unlike disabling – is an irreversible operation. After the key is deleted, it is no longer available. You can refer to the list of API keys to confirm that you removed the old access key.